{% 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	boolean	—	If true, appears in the Component Gallery instead of the main design gallery
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.

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 automatically from the source file’s location under instructions/fragments/uidsl/:

Source path	Category	URL
uidsl/webawesome/badge.mdoc	WebAwesome	/showroom/webawesome
uidsl/forms.mdoc	Forms	/showroom/forms
uidsl/layout.mdoc	Layout	/showroom/layout
uidsl/display.mdoc	Display	/showroom/display
uidsl/navigation.mdoc	Navigation	/showroom/navigation

Files outside of uidsl/ are grouped under /showroom/other.

To add a new category, create a new directory under uidsl/ (e.g. uidsl/charts/) and place your .mdoc snippet files inside it. The compiler will automatically generate a /showroom/charts page and add it to the sidebar.

Custom label overrides for known slugs are defined in SHOWROOM_LABELS in packages/compiler/src/passes/public/index.ts. Add an entry there when the auto-generated label (e.g. Css-conventions → CSS Conventions) needs to be corrected.

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=true 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=true 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 %}