UI DSL Reference

Fragment reference UI DSL Reference

tags

referenceuidslsurface

This reference provides an overview of all structural and interactive components available within the surface tag.

Component Index

The library is divided into semantic categories to help you structure your wireframes effectively. By default, components use the WebAwesome (wa) provider for high-fidelity interactive elements, falling back to StarSpec (wf) for layout primitives and unique components.

Layout

Structural components used to arrange elements in space.

Organizes children in a vertical column. Uses wa-stack under the hood — children stretch to fill the container width by default.

Attributes

Attribute	Type	Default	Description
gap	xs | sm | md | lg | xl	md	Spacing between items.
align	start | center | end | stretch	stretch	Cross-axis alignment of children.

Organizes children in a horizontal line. Uses wa-cluster (default) or wa-split (justify="between").

Attributes

Attribute	Type	Default	Description
gap	xs | sm | md | lg | xl	md	Spacing between items.
justify	start | center | end | between	start	Main-axis distribution.
align	start | center | end | baseline | stretch	center	Cross-axis alignment.

Creates a multi-column grid layout. Uses wa-grid with a fixed grid-template-columns rule.

Attributes

Attribute	Type	Default	Description
cols	number	1	Number of equal-width columns.
gap	xs | sm | md | lg | xl	md	Spacing between cells.

A full-width page container with a dashed wireframe border. Use as the outermost shell of a screen.

Attributes

Attribute	Type	Default	Description
title	string	—	Label shown in the top-left border notch.

Cards group related content in a visually bounded container.

Attributes

Attribute	Type	Default	Description
elevated	boolean	false	Apply a drop shadow for visual lift (DSL shorthand).
orientation	horizontal | vertical	vertical	Card layout direction.
appearance	accent | filled | outlined | filled-outlined | plain	outlined	Visual appearance.

Dividers are used to visually separate or group elements.

Usage

divider

Orientation

Use the orientation attribute to set the direction.

divider(orientation="vertical")

Attributes

Name	Type	Default	Description
orientation	horizontal | vertical	horizontal	Divider orientation.

Scrollers create an accessible container while providing visual cues (fading shadows) that help users identify and navigate through content that scrolls.

Usage

scroller
  row(gap="sm")
    card Item 1
    card Item 2

Attributes

Name	Type	Default	Description
orientation	horizontal | vertical	horizontal	Scroll direction.
without-shadow	boolean	false	Removes the fading edge shadows.
without-scrollbar	boolean	false	Hides the scrollbar while keeping scroll functionality.

Vertical scrolling: Set style="max-height: Xpx" on the scroller to constrain its height and enable vertical overflow.

Buttons

Action triggers and button variants.

Buttons represent actions available to the user.

Attributes

Name	Type	Default	Description
variant	neutral | brand | success | warning | danger	neutral	Semantic variant.
size	small | medium | large	medium	Button size.
appearance	accent | filled | outlined | plain	accent	Visual appearance.
icon	string	-	Icon name placed in the start slot.
pill	boolean	false	Rounded pill shape.
loading	boolean	false	Loading state.
disabled	boolean	false	Disables the button.
with-caret	boolean	false	Adds a dropdown caret indicator.
width	full | auto	auto	Button width (DSL shorthand).

Button groups are used to group related buttons into sections.

Usage

button-group(label="Actions")
  button Left
  button Center
  button Right

Orientation

Use the orientation attribute to create a vertical group.

button-group(label="Options" orientation="vertical")
  button Button A
  button Button B

Attributes

Name	Type	Default	Description
label	string	-	Accessible label.
orientation	horizontal | vertical	horizontal	Group orientation.

Floating Action Button (FAB) fixed to a corner of the screen.

Attributes

Attribute	Type	Default	Description
icon	string	-	Icon name.
position	top-left | top-right | bottom-left | bottom-right	bottom-right	Fixed corner position.
variant	primary | secondary | danger	primary	Visual style.

floatbutton(icon="plus")
floatbutton(icon="edit" position="bottom-left" variant="secondary")

Display

Components for presenting text, media, and status information.

Visual hierarchy markers.

Attributes

Attribute	Type	Default	Description
level	1 | 2 | 3	1	Font size and emphasis level.

heading(level="1") Page Title
heading(level="2") Section Header
heading(level="3") Subsection

Body copy and descriptive text.

Attributes

Attribute	Type	Default	Description
size	sm | md | lg	md	Font size.
muted	boolean	false	Apply a lighter color.
color	muted	-	Alias for muted=true.
weight	bold	-	Bold weight.

text Regular body copy.
text(size="sm" color="muted") Supporting caption text.
text(weight="bold") Bold label

Badges are used to draw attention and display statuses or counts.

Usage

badge Badge

Variants

Set the variant attribute to change the badge’s theme.

badge(variant="brand") Brand
badge(variant="success") Success
badge(variant="warning") Warning
badge(variant="danger") Danger

Appearance

Use the appearance attribute to change the badge’s visual appearance.

badge(appearance="filled" variant="neutral") Filled
badge(appearance="outlined" variant="neutral") Outlined

Pill Badges

Use the pill attribute to give badges rounded edges.

badge(variant="brand" pill) Brand

Start & End Decorations

Use the icon attribute to add presentational elements alongside the badge’s label.

badge(icon="acorn") Start

Attributes

Name	Type	Default	Description
variant	brand | neutral | success | warning | danger	brand	The badge’s theme variant.
appearance	accent | filled | outlined | filled-outlined	accent	The badge’s visual appearance.
pill	boolean	false	Draws a pill-style badge with rounded edges.
attention	none | pulse | bounce	none	Adds an animation to draw attention.

Contextual feedback messages.

Attributes

Attribute	Type	Default	Description
variant	info | success | warning | error	info	Visual style.
title	string	-	Bold header text.
message	string	-	Secondary descriptive text.

Callouts are used to display important messages inline.

Usage

callout This is a standard callout.

Variants

Set the variant attribute to change the callout’s semantic intent.

callout(variant="brand") Informative callout
callout(variant="success") Success message
callout(variant="danger") Danger/error message

Sizes

Use the size attribute to change a callout’s size.

callout(size="small") Small tip
callout(size="medium") Standard callout
callout(size="large") Important message

Icons

Add an icon using the icon attribute, which maps to the icon slot.

callout(icon="circle-info") Information available

Attributes

Name	Type	Default	Description
variant	brand | neutral | success | warning | danger	brand	The callout’s theme variant.
size	small | medium | large	medium	The callout’s size.
appearance	accent | filled | outlined | plain | filled-outlined	filled-outlined	Visual appearance.

Icons are symbols representing options or states.

Usage

Basic icon by name

puguiicon wa-icon-basic

icon(name="gear")

Sizes

Icons scale with font-size. Set style="font-size: 2em" on the icon or a parent element — there is no size attribute.

Icon sizing via font-size style

puguiicon wa-icon-sizes

row(gap="md" align="center")
  icon(name="gear" style="font-size:1em")
  icon(name="gear" style="font-size:1.5em")
  icon(name="gear" style="font-size:2em")
  icon(name="gear" style="font-size:3em")

Variants

Icon stroke-weight variants

puguiicon wa-icon-variants

row(gap="md" align="center")
  icon(name="star" variant="solid" style="font-size:1.5em")
  icon(name="star" variant="regular" style="font-size:1.5em")
  icon(name="star" variant="light" style="font-size:1.5em")
  icon(name="star" variant="thin" style="font-size:1.5em")

Colors

Icons inherit currentColor. Use style="color: var(--wa-color-{hue}-{tint})" where tint is a 2-digit value on the 05–95 scale (e.g. --wa-color-green-60).

Icon semantic color usage

puguiicon wa-icon-colors

row(gap="md" align="center")
  icon(name="circle-check" variant="solid" style="font-size:1.5em;color:var(--wa-color-green-60)")
  icon(name="triangle-exclamation" variant="solid" style="font-size:1.5em;color:var(--wa-color-yellow-50)")
  icon(name="circle-xmark" variant="solid" style="font-size:1.5em;color:var(--wa-color-red-60)")
  icon(name="circle-info" variant="solid" style="font-size:1.5em;color:var(--wa-color-blue-60)")

Attributes

Name	Type	Default	Description
name	string	-	Icon name.
label	string	-	Accessible description.
variant	solid | regular | light | thin	regular	Icon variant.
rotate	number	0	Rotation in degrees.
flip	x | y | both	-	Flip direction.

Avatars represent a person or object.

Usage

avatar(label="User")

Content

Avatars support images, initials, or icons.

avatar(image="/images/user.jpg" label="User Photo")
avatar(initials="JD" label="John Doe")
avatar(label="Empty")
  icon(slot="icon" name="person")

Attributes

Name	Type	Default	Description
image	string	-	Image source URL.
initials	string	-	Fallback initials.
label	string	-	Accessible description.
shape	circle | square | rounded	circle	Avatar shape.
loading	eager | lazy	eager	Image loading strategy.

Tags are used as labels to organize things or to indicate a selection.

Usage

tag Brand

Variants

Set the variant attribute to change the tag’s theme.

tag(variant="brand") Brand
tag(variant="success") Success
tag(variant="danger") Danger

Sizes

Use the size attribute to change a tag’s size.

tag(size="small") Small
tag(size="medium") Medium
tag(size="large") Large

Attributes

Name	Type	Default	Description
variant	brand | neutral | success | warning | danger	neutral	The tag’s theme variant.
size	small | medium | large	medium	The tag’s size.
appearance	accent | filled | outlined | filled-outlined	filled-outlined	Visual appearance.
pill	boolean	false	Draws a pill-style tag with rounded edges.
with-remove	boolean	false	Shows a remove button.

Spinners show the progress of an indeterminate operation.

Usage

spinner

Attributes

Name	Type	Default	Description
-	-	-	None.

Conversational message layout.

Attributes

Attribute	Type	Default	Description
variant	sent | received	received	Message ownership and alignment.
timestamp	string	-	Small time text (e.g. 10:42 AM).
status	sent | delivered | read	-	Message status indicator.

Animated conversational activity indicator. Use inside or after a chat-bubble to show that the other party is composing a reply.

stack(gap="sm")
  chat-bubble(variant="received")
    text One moment…
  typing-dots

Provides a declarative way to create animations for web components.

Usage

animation(name="fade-in" duration=500 play=true)
  div Content to animate

Attributes

Name	Type	Default	Description
name	string	-	Animation name.
duration	number	1000	Duration in ms.
play	boolean	true	Animation play state.

Displays an animated image (e.g., GIF) that can be paused and played.

Usage

animated-image(src="image.gif" alt="Animated GIF")

Attributes

Name	Type	Default	Description
src	string	-	Image URL.
alt	string	-	Alt text.
play	boolean	true	Animation state.

Forms & Input

Interactive elements for gathering user data.

Inputs collect data from the user.

Usage

Basic input with label

puguiinput wa-input-basic

input(label="Name")

Types

The type attribute controls the type of input the browser renders.

Input type variants

puguiinput wa-input-types

input(label="Email" type="email")
input(label="Date" type="date")

Options

Add interactive features with shorthand attributes.

Input with clear button and password toggle

puguiinput wa-input-options

input(label="Nickname" placeholder="What should we call you?" with-clear)
input(label="Password" type="password" password-toggle)

Sizes

Use the size attribute to change an input’s size.

Input size scale

puguiinput wa-input-sizes

input(label="Small" size="small")
input(label="Medium" size="medium")
input(label="Large" size="large")

Attributes

Name	Type	Default	Description
label	string	-	The input label.
placeholder	string	-	Placeholder text.
type	text | email | number | password | date	text	Input type.
size	small | medium | large	medium	Input size.
disabled	boolean	false	Prevents interaction.
required	boolean	false	Marks as required.
with-clear	boolean	false	Shows a clear button.
password-toggle	boolean	false	Shows a toggle button for password visibility.

Textareas collect data from the user and allow multiple lines of text.

Usage

textarea(label="Comments")

Options

Add interactive features with shorthand attributes.

textarea(label="Feedback" placeholder="What do you think?" with-count)

Attributes

Name	Type	Default	Description
label	string	-	The textarea label.
placeholder	string	-	Placeholder text.
rows	number	4	Number of rows.
resize	none | vertical | horizontal | both | auto	vertical	Resizing behavior.
size	small | medium | large	medium	Textarea size.
disabled	boolean	false	Prevents interaction.
required	boolean	false	Marks as required.
with-count	boolean	false	Shows a character count.

Dropdown selection menu.

Attributes

Attribute	Type	Default	Description
options	string	-	Comma-separated list of options.
open	boolean	false	Whether the dropdown is visible.
label	string	-	Label text.
value	string	-	Selected value.
placeholder	string	Select...	Hint text when no value is selected.
adaptive	boolean	false	Renders as a bottom sheet (mobile-optimized).
searchable	boolean	false	Adds a search input to the option list.
disabled	boolean	false	Prevents interaction.
status	success | error	-	Visual validation state.
message	string	-	Validation message.

Checkboxes allow the user to toggle an option on or off.

Usage

checkbox Label text

States

Control the state using boolean attributes.

checkbox(checked) Checked
checkbox(indeterminate) Indeterminate
checkbox(disabled) Disabled

Sizes

Use the size attribute to change a checkbox’s size.

checkbox(size="small") Small
checkbox(size="medium") Medium
checkbox(size="large") Large

Attributes

Name	Type	Default	Description
checked	boolean	false	Drawn in a checked state.
indeterminate	boolean	false	Drawn in an indeterminate state.
disabled	boolean	false	Prevents interaction.
size	small | medium | large	medium	Checkbox size.
required	boolean	false	Marks as required.

Radios allow the user to select a single option from a group. They must be used inside a radio-group.

Usage

radio(value="1") Option 1

Attributes

Name	Type	Default	Description
value	string	-	Value submitted when selected.
disabled	boolean	false	Prevents interaction.
size	small | medium | large	medium	Radio size.

Radio groups are used to group multiple radios so they function as a single form control.

Usage

radio-group(label="Select an option" name="options" value="A")
  radio(value="A") Option A
  radio(value="B") Option B

Orientation

Use orientation to switch between horizontal and vertical layouts.

radio-group(orientation="horizontal")
  radio(value="A") A
  radio(value="B") B

Attributes

Name	Type	Default	Description
label	string	-	Accessible label.
name	string	-	Name attribute for form submission.
value	string	-	Currently selected value.
orientation	horizontal | vertical	vertical	Layout direction.
size	small | medium | large	medium	Size for all contained radios.
required	boolean	false	Marks as required.

Ranges allow the user to select a value within a range.

Usage

slider(label="Volume" min=0 max=100 value=50)

Features

Enable range mode or show additional UI elements.

slider(label="Range" range min=0 max=100 min-value=20 max-value=80)
slider(label="Markers" with-markers min=0 max=10 value=5)

Tooltips

Use with-tooltip to show the current value.

slider(label="Quality" with-tooltip min=0 max=100 value=50)

Attributes

Name	Type	Default	Description
label	string	-	Accessible label.
min	number	0	Minimum value.
max	number	100	Maximum value.
value	number	-	Current value.
range	boolean	false	Enables dual-thumb range selection.
min-value	number	0	Minimum value for range mode.
max-value	number	50	Maximum value for range mode.
with-tooltip	boolean	false	Shows a value tooltip.
with-markers	boolean	false	Shows step markers.
size	small | medium | large	medium	Component size.
disabled	boolean	false	Prevents interaction.

Color pickers allow the user to select a color.

Usage

color-picker(label="Select a color")

Formats

Use the format attribute to control the color format.

color-picker(label="Hex" format="hex")
color-picker(label="RGB" format="rgb")

Features

Enable features like opacity and swatches.

color-picker(label="With opacity" opacity)
color-picker(label="With swatches" swatches="#f00; #0f0; #00f")

Attributes

Name	Type	Default	Description
label	string	-	Accessible label.
format	hex | rgb | hsl | hsv	hex	Output color format.
opacity	boolean	false	Enables opacity slider.
swatches	string	-	Semicolon-separated color swatches.
size	small | medium | large	medium	Component size.
disabled	boolean	false	Prevents interaction.

Toggles an option on or off.

Usage

switch(checked) Label

Attributes

Name	Type	Default	Description
checked	boolean	false	Current state.
disabled	boolean	false	Prevents interaction.

Ratings give users a way to quickly view and provide feedback. Integrates with standard form elements.

Usage

rating(label="Rate this" value=3)

Labels

Always provide a label for assistive devices — it is not displayed visually but is required for accessibility.

rating(label="Rate this component")

Maximum Value

Use max to change the highest rating. Default is 5.

rating(label="Rating" max=3)
rating(label="Rating" max=10)

Precision

Use precision to allow fractional ratings.

rating(label="Rating" precision=0.5 value=2.5)

Sizing

Use size to adjust the component size.

rating(label="Rating" size="small")
rating(label="Rating" size="medium")
rating(label="Rating" size="large")

Readonly

Use readonly to display a rating that users cannot change.

rating(label="Rating" readonly value=4)

Disabled

Use disabled to prevent all interaction.

rating(label="Rating" disabled value=3)

Attributes

Name	Type	Default	Description
label	string	''	Accessible label for assistive devices (not displayed visually).
value	number	0	The current rating value.
max	number	5	The highest rating to show.
precision	number	1	Increment precision. Use 0.5 for half-star ratings.
size	'small' | 'medium' | 'large'	'medium'	The component’s size.
readonly	boolean	false	Prevents user interaction without disabling the element.
disabled	boolean	false	Disables the rating entirely.
required	boolean	false	Makes the rating required in a form context.
name	string	null	Form field name submitted with form data.

Specialized multi-box input for verification codes.

Attributes

Attribute	Type	Default	Description
length	number	4	Number of digit boxes.
secure	boolean	false	Renders bullets instead of clear text.
label	string	-	Label text.
message	string	-	Validation or hint message.

Calendar date selection.

Attributes

Attribute	Type	Default	Description
label	string	-	Label text.
value	string	-	Current date value (ISO format).
disabled	boolean	false	Prevents interaction.
A row of mutually exclusive buttons (segmented control).

Attributes

Attribute	Type	Default	Description
options	string	-	Shorthand for comma-separated labels.
value	string	-	Selected value in shorthand mode.

Can also contain segment children for icon support:

segmented
  segment(label="Left" icon="align-left" active=true)
  segment(label="Center" icon="align-center")
  segment(label="Right" icon="align-right")

Navigation

Components for organizing multi-screen or multi-state interfaces.

Application navigation shell. Supports top bar, sidebar, and breadcrumb modes. Contains link children.

Attributes

Attribute	Type	Default	Description
type	top | side | breadcrumb	top	Navigation layout.
brand	string	-	Brand/app name (top bar only).
search	boolean	false	Show a search input (top bar only).

Switches between mutually exclusive content panels. Contains tab children; the child marked active is rendered.

Tab attributes

Attribute	Type	Default	Description
label	string	-	Text on the tab header.
icon	string	-	Icon on the tab header.
active	boolean	false	Whether this tab is selected.

tabs
  tab(label="Overview" active=true)
    text Overview content here.
  tab(label="Settings")
    text Settings content here.
  tab(label="History" icon="clock")
    text History content here.

Tab groups (tabs) organize content into distinct views. Each tab is a header and its content body in one — no separate tab-panel needed in the DSL.

Usage

Basic tab group with three tabs

puguitab-group wa-tabs-basic

tabs(label="Settings")
  tab(label="General") General content.
  tab(label="Privacy") Privacy content.
  tab(label="Advanced") Advanced content.

Vertical placement

Tab group with vertical side placement

puguitab-group wa-tabs-vertical

tabs(label="Navigation" placement="start")
  tab(label="Overview") Overview content.
  tab(label="Details") Details content.
  tab(label="History") History content.

Disabled tab

Tab group with a disabled tab

puguitab-group wa-tabs-disabled

tabs(label="Example")
  tab(label="Active") Active tab content.
  tab(label="Another") Another tab content.
  tab(label="Disabled" disabled) This tab is disabled.

Attributes — tabs (tab-group)

Name	Type	Default	Description
label	string	-	Accessible label for the group.
placement	top | bottom | start | end	top	Tab strip position.
activation	auto | manual	auto	auto activates on focus; manual requires a click.
no-scroll-controls	boolean	false	Hides scroll arrows when tabs overflow.

Attributes — tab

Name	Type	Default	Description
label	string	-	Tab header text.
disabled	boolean	false	Disables the tab.

Collapsible content panels. The DSL alias panel maps to wa-details.

Attributes

Attribute	Type	Default	Description
label	string	-	Header text (DSL). Maps to summary in wa-details.
summary	string	-	Header text (wa-details).
open	boolean	false	Whether the panel is expanded.
disabled	boolean	false	Prevents toggling.
icon-placement	start | end	end	Toggle icon position.
appearance	filled | outlined | filled-outlined | plain	outlined	Visual appearance.

A linear sequence of steps. Contains step children.

Stepper attributes

Attribute	Type	Default	Description
orientation	horizontal | vertical	horizontal	Layout direction.

Step attributes

Attribute	Type	Default	Description
label	string	-	Step title.
description	string	-	Optional subtitle.
status	pending | active | completed	pending	Current state.

Breadcrumbs show the current location in a hierarchy. Each breadcrumb-item is a navigation step; the last one represents the current page and is rendered without a link.

Usage

breadcrumb
  breadcrumb-item(href="/home") Home
  breadcrumb-item(href="/products") Products
  breadcrumb-item Current Page

Attributes — breadcrumb

Name	Type	Default	Description
label	string	Breadcrumb	Accessible aria-label for the nav element.

Attributes — breadcrumb-item

Name	Type	Default	Description
href	string	-	Makes the item a link. Omit for the current/last item.
target	string	-	Link target (e.g. _blank).
rel	string	-	Link relationship.

Slots — breadcrumb-item

Slot	Description
start	Icon or element before the label.
end	Icon or element after the label.

Slots — breadcrumb

Slot	Description
separator	Custom separator between items (default is /).

Command menus or context menus. Contains menu-item children.

Attributes

Attribute	Type	Default	Description
label	string	-	Trigger button text.
open	boolean	true	Whether the menu is visible.
variant	dropdown | list	dropdown	Inline list or absolute dropdown.

menu(label="Actions" open=true)
  menu-item Edit
  menu-item Duplicate
  menu-item(danger=true) Delete

Dropdowns display a list of options that can be triggered by a button or other element.

Usage

Basic dropdown with trigger button and items

puguidropdown wa-dropdown-basic

dropdown
  button(slot="trigger" with-caret) Options
  dropdown-item(value="1") Option 1
  dropdown-item(value="2") Option 2

Item variants

Dropdown with checkbox and danger item variants

puguidropdown wa-dropdown-item-variants

dropdown
  button(slot="trigger" with-caret) Actions
  dropdown-item(value="edit") Edit
  dropdown-item(value="dupe") Duplicate
  dropdown-item(type="checkbox" checked value="pin") Pinned
  dropdown-item(value="delete" variant="danger") Delete

Attributes

Name	Type	Default	Description
open	boolean	false	Visibility state.
size	small | medium | large	medium	Component size.
placement	top | bottom | left | right	bottom-start	Popup positioning.

Represents an individual item within a dropdown menu. Must be used as a child of a dropdown.

Usage

dropdown-item(value="1") Option 1

Attributes

Name	Type	Default	Description
value	string	-	Value identifier.
type	normal | checkbox	normal	Item type.
checked	boolean	false	If checked (for checkbox type).
disabled	boolean	false	Prevents interaction.
variant	default | danger	default	Item variant.

Interruptive overlay dialog. The DSL alias modal maps to wa-dialog.

Note: The modal component is temporarily disabled in wireframe previews to avoid interfering with the documentation interface. Use modal=false to render inline for wireframes.

Attributes

Attribute	Type	Default	Description
title	string	-	Header title.
open	boolean	true	Visibility state.
size	sm | md | lg	md	Dialog width (DSL).
variant	alert	-	Visual intent (e.g. destructive warning).
native	boolean	false	Renders a system-native alert style.
modal	boolean	true	If false, renders as an inline sheet (wireframe mode).
without-header	boolean	false	Hides the header.
light-dismiss	boolean	false	Closes on clicking outside.

Drawers slide in from a container to expose additional options and information.

Usage

drawer(label="Drawer Title")
  text Content goes here

Placement

Use the placement attribute to control where the drawer slides from.

drawer(label="Drawer" placement="start")

Attributes

Name	Type	Default	Description
label	string	-	Header title.
open	boolean	true	Visibility state.
placement	start | end | top | bottom	end	Slide-in direction.
without-header	boolean	false	Hides the header.
light-dismiss	boolean	true	Closes on clicking outside.

Trees display a hierarchical list of selectable items. Items with children can be expanded and collapsed. The icon shorthand on tree-item prepends a wa-icon before the label text.

Usage

Collapsible tree with nested items

puguitree wa-tree-basic

tree
tree-item(expanded) Documents
tree-item Reports
tree-item Archive
tree-item Downloads

Attributes — tree

Name	Type	Default	Description
selection	single | multiple | leaf	single	Selection behaviour. multiple shows checkboxes. leaf restricts selection to leaf nodes only.

Attributes — tree-item

Name	Type	Default	Description
expanded	boolean	false	Expand state on initial render.
selected	boolean	false	Mark item as selected.
lazy	boolean	false	Marks the item as not yet loaded; emits wa-lazy-load on first expand.

CSS Custom Properties — tree

Name	Default	Description
--indent-guide-width	0	Width of the indent guide line. Set to 1px to show guides.
--indent-guide-color	surface border	Color of the indent guide.
--indent-guide-style	solid	Line style: solid, dashed, dotted.
--indent-size	var(--wa-space-m)	Indentation depth per level.

Text content: tree-item uses inline text, not a label attribute. Write tree-item(expanded) Folder Name — not tree-item(label="Folder Name").

Navigation link. Used inside nav, breadcrumb mode, and as standalone inline links.

Attributes

Attribute	Type	Default	Description
label	string	-	Link text.
icon	string	-	Icon name.
active	boolean	false	Marks the current/active route.
count	number	-	Badge count shown alongside the label.
href	string	-	URL destination.

link(label="Dashboard" icon="home" active=true)
link(label="Notifications" count=5)

Data

Components for presenting structured data, metrics, and progress.

Dashboard metric cards with trend indicators.

Attributes

Attribute	Type	Default	Description
label	string	-	Metric name (e.g. Revenue).
value	string	-	Primary numeric value.
trend	string	-	Secondary trend text (e.g. +12%).
direction	up | down	-	Visual direction for the trend color.

Tabular data display. Contains column children.

Table attributes

Attribute	Type	Default	Description
rows	number	3	Number of placeholder rows.
striped	boolean	false	Alternate row background colors.

Column attributes

Attribute	Type	Default	Description
label	string	-	Header text.
width	string	auto	CSS width (e.g. 20%).
align	left | center | right	left	Text alignment.

table(rows=4 striped=true)
  column(label="Name" width="40%")
  column(label="Status" width="20%" align="center")
  column(label="Date" width="20%")
  column(label="Amount" width="20%" align="right")

Simple vertical collection.

Attributes

Attribute	Type	Default	Description
type	bullet | ordered | none	bullet	Marker style.
count	number	3	Number of placeholder items.
item	string	item	Label shown in each placeholder item.

list(type="bullet" count=4 item="Feature")
list(type="ordered" count=3 item="Step")

A vertical chronological sequence of events. Contains timeline-item children.

timeline-item attributes

Attribute	Type	Default	Description
label	string	-	Primary event text.
description	string	-	Secondary details or timestamp.
icon	string	-	Marker icon name.
status	pending | active | completed	completed	State of the event.

Visual completion indicators. Two variants: progress-bar (linear) and progress-ring (circular).

---

progress-bar

Linear progress indicator. Shows the status of an ongoing operation.

Attributes

Name	Type	Default	Description
value	number	0	Current progress percentage (0–100).
indeterminate	boolean	false	Sets indeterminate state when progress cannot be determined.
label	string	-	Accessible label.

---

progress-ring

Circular progress indicator.

Attributes

Name	Type	Default	Description
value	number	0	Current progress percentage (0–100).
size	number	-	Size in pixels.

---

progress (DSL)

DSL alias for generic visual completion state.

Attribute	Type	Default	Description
label	string	-	Descriptive text.
value	number	0	Current progress.
max	number	100	Target value.
Generates a QR code rendered using the Canvas API.

Attributes

Name	Type	Default	Description
value	string	-	Data to encode.
size	number | sm | md | lg	128	Size in pixels (or DSL size token).
label	string	-	Accessible description.
radius	number	0	Edge radius (0 to 0.5).
error-correction	L | M | Q | H	H	Error correction level.

Three formatting components backed by browser-native Intl APIs — no language packs required.

• format-number — decimals, percentages, currencies via Intl.NumberFormat
• format-date — dates, times, weekdays via Intl.DateTimeFormat
• format-bytes — byte/bit sizes with configurable verbosity

Attributes — format-number

Name	Type	Default	Description
value	number	0	Number to format.
type	decimal | currency | percent	decimal	Formatting style.
currency	string	USD	ISO 4217 currency code. Used when type="currency".
currency-display	symbol | narrowSymbol | code | name	symbol	How to display the currency.
minimum-fraction-digits	number	-	Minimum decimal places (0–100).
maximum-fraction-digits	number	-	Maximum decimal places (0–100).
without-grouping	boolean	false	Disables thousands separator.
lang	string	browser default	BCP 47 locale tag (e.g. en-US, de).

Attributes — format-date

Name	Type	Default	Description
date	string | Date	new Date()	ISO 8601 date string to format.
weekday	narrow | short | long	-	Display format for the weekday.
year	numeric | 2-digit	-	Display format for the year.
month	numeric | 2-digit | narrow | short | long	-	Display format for the month.
day	numeric | 2-digit	-	Display format for the day.
hour	numeric | 2-digit	-	Display format for the hour.
minute	numeric | 2-digit	-	Display format for the minute.
second	numeric | 2-digit	-	Display format for the second.
hour-format	auto | 12 | 24	auto	12- or 24-hour clock.
time-zone	string	-	IANA time zone name (e.g. America/New_York).
lang	string	browser default	BCP 47 locale tag (e.g. en-US, fr).

Attributes — format-bytes

Name	Type	Default	Description
value	number	0	Value to format.
unit	byte | bit	byte	Display as bytes or bits.
display	long | short | narrow	short	Label verbosity: “100 bytes”, “100 B”, “100B”.
lang	string	browser default	BCP 47 locale tag for number formatting.

Always use ISO 8601 for dates. Avoid 03/04/2026 — browsers may interpret month/day order differently.

Numeric formatting with decimal, percent, and currency

puguiformat wa-format-number

format-number(value=12345.67)
format-number(value=0.753 type="percent")
format-number(value=2000 type="currency" currency="USD" lang="en-US")

Date formatting with long month, weekday, and time

puguiformat wa-format-date

format-date(date="2026-04-30T12:00:00Z" month="long" day="numeric" year="numeric")
format-date(date="2026-04-30T12:00:00Z" weekday="long")
format-date(date="2026-04-30T14:30:00Z" hour="numeric" minute="numeric" hour-format="12")

Byte size formatting with display verbosity variants

puguiformat wa-format-bytes

format-bytes(value=512)
format-bytes(value=1572864 display="long")
format-bytes(value=1572864 display="short")
format-bytes(value=1572864 display="narrow")

Outputs a localized time phrase relative to the current date and time. Localization is handled by the browser’s Intl.RelativeTimeFormat API — no language packs required.

Usage

relative-time(date="2026-04-29T10:00:00Z")

Attributes

Name	Type	Default	Description
date	string | Date	new Date()	ISO 8601 date string to calculate from.
format	long | short | narrow	long	Display style.
numeric	auto | always	auto	auto shows “yesterday”; always shows “1 day ago”.
lang	string	browser default	BCP 47 language tag (e.g. en-US, de, zh-CN).
sync	boolean	false	Auto-updates as time passes.

Dates must be ISO 8601. Avoid ambiguous formats like 03/04/2026 — always use YYYY-MM-DDTHH:MM:SSZ.

Charts

Data visualization components.

Visual data representations.

Attributes

Attribute	Type	Default	Description
type	radial | area | bar	area	Chart visualization pattern.
value	number	50	Percentage value (for radial type).
label	string	-	Descriptive legend text.

Widgets

Interactive content widgets.

Carousels display content slides along a horizontal or vertical axis.

Usage

carousel
  carousel-item Slide 1
  carousel-item Slide 2

Features

Enable navigation and pagination.

carousel(navigation pagination loop)
  carousel-item Slide 1
  carousel-item Slide 2

Attributes

Name	Type	Default	Description
navigation	boolean	false	Shows nav arrows.
pagination	boolean	false	Shows dots.
loop	boolean	false	Enable infinite loop.
autoplay	boolean	false	Auto-advance slides.
orientation	horizontal | vertical	horizontal	Axis of movement.

Must be used inside a carousel.

Usage

carousel-item This is a slide.

Compares two content regions side-by-side with a draggable divider. Works best when both sides share the same dimensions. The handle can be dragged or controlled with arrow keys (Shift+arrows for larger steps, Home/End to jump to edges).

Usage

comparison
  img(slot="before" src="before.jpg" alt="Before")
  img(slot="after" src="after.jpg" alt="After")

Attributes

Name	Type	Default	Description
position	number	50	Initial divider position as a percentage (0–100).

CSS Custom Properties

Name	Description
--divider-width	Width of the dividing line.
--handle-size	Size of the drag handle.

Allows zooming into content within a container.

Usage

Zoomable frame with min/max zoom bounds

puguizoomable-frame wa-zoomable-frame-basic

zoomable-frame(min-zoom=0.5 max-zoom=3 src="/showroom")

Attributes

Name	Type	Default	Description
min-zoom	number	0.1	Minimum zoom level.
max-zoom	number	5	Maximum zoom level.

Placeholder & Skeleton

Generic placeholders and loading states.

Generic content placeholders for wireframe layouts. Renders a visually distinct blocked area to represent content not yet designed.

Attributes

Attribute	Type	Default	Description
type	text | image | chart | avatar | video | card	text	Visual pattern.
skeleton	boolean	false	Apply animated loading skeleton state.
width	string	-	CSS width (e.g. 100%).
height	string	-	CSS height (e.g. 200px).
ratio	string	-	CSS aspect-ratio (e.g. 16/9).
lines	number	1	Number of text lines (text type only).
label	string	-	Label text.

placeholder(type="image" ratio="16/9" label="Hero Banner")
placeholder(type="chart" height="200px")
placeholder(type="avatar" width="48px" height="48px")

skeleton renders a visual standin for content that is loading or not yet designed. placeholder is an alias — both render as wa-skeleton.

Use placeholder in wireframes for deferred visual areas. Use skeleton when explicitly modelling a loading state.

Attributes

Attribute	Type	Default	Description
effect	none | pulse | sheen	none	Animation effect. sheen is a left-to-right sweep; pulse fades in and out.
style	string	—	Inline CSS for sizing and border-radius.

Sizing: wa-skeleton is a block element that stretches to fill its container by default. Control dimensions with the style attribute.

Shape: Use style="border-radius: 50%" for circular variants. Use style="border-radius: var(--wa-border-radius-m)" for rounded.

Color: Override fill and sweep color via --color and --sheen-color CSS custom properties.

Common patterns

Text block

stack(gap="xs")
  skeleton(effect="sheen")
  skeleton(effect="sheen")
  skeleton(effect="sheen" style="width: 65%")

Avatar (circle)

skeleton(style="width: 48px; height: 48px; border-radius: 50%")

Avatar + text row

row(align="center" gap="md")
  skeleton(style="width: 40px; height: 40px; border-radius: 50%; flex-shrink: 0")
  stack(gap="xs" style="flex: 1")
    skeleton(effect="sheen")
    skeleton(effect="sheen" style="width: 50%")

Image / media box

skeleton(effect="sheen" style="height: 180px")

Card skeleton

card
  stack(gap="sm")
    skeleton(effect="sheen" style="height: 120px")
    skeleton(effect="sheen")
    skeleton(effect="sheen" style="width: 70%")
    row(gap="sm")
      skeleton(effect="sheen" style="width: 80px; height: 32px")
      skeleton(effect="sheen" style="width: 80px; height: 32px")

Table rows

stack(gap="xs")
  skeleton(style="height: 36px")
  skeleton(effect="pulse")
  skeleton(effect="pulse")
  skeleton(effect="pulse")

Patterns

Common multi-component screen layout patterns.

Full screen shell with a header row (title + icon), a primary card, and a secondary card.

Form screen shell with a title block, an elevated card containing inputs, and a submit button.

List screen shell with a header row, search input, and a stack of card list items.

Settings screen shell with a heading, an elevated preferences card containing divider-separated control rows.

---

Layout Strategy

When building a surface, follow these hierarchical levels:

1. Shell: Use nav (top/side) to define the application frame.
2. Sectioning: Use section (wf) to group related cards or stacks.
3. Grouping: Use card (wa) to encapsulate related inputs or data.
4. Flow: Use stack (wf, vertical) and row (wf, horizontal) to manage spacing and alignment of atomic components.

For more details on styling and theming, see Wireframe CSS.