{% surface %}

Attributes

Parameter	Type	Required	Description
id	string	✓	Unique kebab-case surface id (e.g., 'login-form')
title	string	✓	Human-readable screen name
type	enum	—	atomic | widget | screen
feature	string	—	Qualified id of the feature or flow this surface represents
showroom	string	—	Category path for the Component Gallery (e.g. 'Forms', 'Patterns/Ecommerce'). Supports '/' for hierarchy.
group	string	—	UIs with the same group ID are rendered together in a tabbed view
label	string	—	The tab label used when this surface is part of a group. Defaults to title.
width	string	—	CSS min-width for the surface container in the gallery (e.g. '600px', '40rem')

Valid Children

Tag	Multiplicity
{% interactions %}	[*]

Valid Parent Contexts

This tag is valid inside: {% feature %}, {% story %}

Rules

Rule	Force	Realm	Reference	Description
surface-pug-strict-subset	must	global	—	Only Pug tags, attributes, and nesting are supported. No mixins, includes, or JavaScript logic. validationdsl
surface-atomic-no-children	must	global	—	Atomic components (like , ) cannot have children. validationdsl
surface-textual-text-only	must	global	—	Textual components (like , ) can only contain text or string references. validationdsl
surface-container-any	must	global	—	Container components (like , ) can contain any other valid components. validationdsl

The surface tag allows you to author low-fidelity wireframes directly in your specification using a subset of Pug compiled into themed HTML elements. See the UI DSL Reference for all available components.

Live interactive examples for every component are available in the Component Gallery.

Component Gallery Categories

The Component Gallery at /showroom is split into sub-pages by category to keep page load times fast. Each category page loads only its own surfaces.

The category is determined by the showroom attribute value on each surface. The value is a category path that supports / for hierarchical grouping:

showroom value	Category page	Sidebar
"Forms"	/showroom/forms	Top-level link
"Buttons"	/showroom/buttons	Top-level link
"Patterns/Ecommerce"	/showroom/patterns/ecommerce	Nested under “Patterns”
"Patterns/Blog"	/showroom/patterns/blog	Nested under “Patterns”

To add a new category, simply use a new showroom value on a surface. The compiler will automatically generate a page and sidebar entry for it. Hierarchical paths create nested sidebar groups.

Login form wireframe with Pug DSL

tagsurfacepug surface-tag-login

{% surface id="login-form" title="User Login" %}
```pug
card
  stack(gap="lg")
    heading(level="1") Login to your account
    stack(gap="md")
      input(label="Email" placeholder="user@example.com" required)
      input(label="Password" type="password" required)
    row(justify="between")
      checkbox Remember me
      button(variant="ghost") Forgot password?
    button(variant="primary") Login
```
{% /surface %}

Multiple surface variants rendered in a tabbed view using group and label

tagsurfaceshowroomgroup surface-tag-showroom-variants

{% surface id="tabs-example" title="Tabbed Variants" showroom="Examples" group="tabs-demo" label="Basic" %}
```pug
stack(gap="md")
  heading(level="2") Basic Tab
  text This is the first tab content.
```
{% /surface %}

{% surface id="tabs-example-2" title="Tabbed Variants" showroom="Examples" group="tabs-demo" label="Advanced" %}
```pug
stack(gap="md")
  heading(level="2") Advanced Tab
  text This is the second tab content with more complex layout.
  button(variant="primary") Action
```
{% /surface %}