StarSpec Reference

StarSpec is a specification compiler. Authors write .mdoc files; the compiler produces agent bundles (TOON) and a Starlight documentation site (MDX). This index covers all available instruction paths.

Agents

Seven agents interact with this system. Each has a dedicated entry point in starspec/agents/*.agent.mdoc.

Agent	Entry point	Responsibility
starscribe	starspec/agents/starscribe	Creates and extends spec documents: roles, domains, features, flows, stories, manifests, milestones, changesets, blueprints
starfix	starspec/agents/starfix	Enforces conventions, runs lint and sanitize workflows, audits naming
stardesign	starspec/agents/stardesign	Creates and iterates UI surface documents using the Pug DSL
starspec	starspec/agents/starspec	Evolves the compiler itself: adds tags, modifies processors, adds aggregate pages
starvision	starspec/agents/starvision	Extracts wireframe themes from screenshots
starmemo	starspec/agents/starmemo	Manages memos and pre-spec notes
starticle	starspec/agents/starticle	Authors and reviews long-form articles
consumer	starspec/consumer (this index)	Reads compiled bundles to drive code generation — does not modify .mdoc files

Handoff rules:

• starscribe → starfix: when a task requires convention enforcement, linting, or sanitization
• starscribe → stardesign: when a task requires authoring or changing a UI surface document
• stardesign → starscribe: when a task requires defining new behaviour, flows, or requirements
• starscribe / stardesign → consumer agent: when spec work is complete and implementation begins — hand off via a changeset

Authoring — create new documents

Intent	Instruction path
Import a conversation transcript	starspec/transcript/import
Audit, list, or derive API items	starspec/agents/starscribe/api.audit
Brainstorm a new initiative	starspec/agents/starscribe/brainstorm.create
Create a role	starspec/agents/starscribe/role.create
Create a domain	starspec/agents/starscribe/domain.create
Create a feature	starspec/agents/starscribe/feature.create
Create a flow	starspec/agents/starscribe/flow.create
Create a story	starspec/agents/starscribe/story.create
Create a manifest	starspec/agents/starscribe/manifest.create
Create a milestone	starspec/agents/starscribe/milestone.create
Create a changeset	starspec/agents/starscribe/changeset.create
Create a blueprint	starspec/agents/starscribe/blueprint.create
Create a UI Surface	starspec/agents/stardesign/surface.create

Authoring — extend existing documents

Intent	Instruction path
Extend a role	starspec/agents/starscribe/role.extend
Extend a domain	starspec/agents/starscribe/domain.extend
Extend a feature	starspec/agents/starscribe/feature.extend
Extend a UI Surface	starspec/agents/stardesign/surface.extend
Audit a UI Surface	starspec/agents/stardesign/surface.audit

Fixing & validation

Intent	Instruction path
Lint and fix schema errors	starspec/agents/starfix/schema.lint
Sanitize semantic model issues	starspec/agents/starfix/model.sanitize

Tag reference — schema and usage rules

Fetch starspec/tag/{name} for any tag. Common ones:

article · blueprint · changeset · criterion · diagram · domain · feature · flow · manifest · milestone · model · policy · property · requirement · role · story · surface · tag · tldr · tour · touched

er StarSpec Tag System

Gallery Source ⛶

Diagram Syntax Error

classDiagram
  direction TB
  note "+ = required  ── = contains  ..> = cross-doc ref"

  %% ─── Document Roots ─────────────────────────────────────────────────────────

  class domain:::root {
    +id : string
    scope : string
  }
  class feature:::root {
    +id : string
    roles : string
    domains : string
    scope : string
  }
  class role:::root {
    +id : string
    +label : string
    scope : string
  }
  class flow:::root {
    +id : string
    scope : string
  }
  class manifest:::root {
    +id : string
    scope : string
  }
  class blueprint:::root {
    +id : string
    +type : infrastructure|architecture|module|plan
    implements : string
    scope : string
  }
  class story:::root {
    +id : string
    +role : string
    +features : string
  }
  class milestone:::root {
    +id : string
    release : string
    status : planned|in-progress|done
    scope : string
  }
  class tour:::root {
    kind : walkthrough|demo|checklist
    transition : none|fade|slide|slide-back
    scale : number
    feature : string
    scope : string
  }
  class surface:::root {
    +id : string
    +title : string
    type : atomic|widget|screen
    feature : string
    showroom : boolean
    group : string
    label : string
    scale : number
  }
  class changeset:::root {
    +commits : string
    scope : string
  }

  %% ─── Universal Tags ──────────────────────────────────────────────────────────

  class tldr {
    scope : string
  }
  class explanation {
    +type : hint|details
    audience : string
    tags : string
    summary : string
    scope : string
  }
  class diagram {
    +id : string
    +label : string
    type : string
    engine : mermaid|d2|dot
  }
  class setting {
    +id : string
    +type : string
    default : string
  }

  %% ─── API Group ───────────────────────────────────────────────────────────────

  class api
  class action {
    +id : string
  }
  class event {
    +id : string
  }
  class operation {
    +id : string
    +type : read|write
    idempotent : boolean
  }
  class error {
    +id : string
    +code : string
    category : domain|technical
  }
  class property {
    +id : string
    +type : string
    required : boolean
    description : string
  }
  class returns
  class throws {
    +ref : string
  }

  %% ─── Domain Children ─────────────────────────────────────────────────────────

  class glossary
  class term {
    +id : string
  }
  class model
  class policy {
    id : string
    +sourceRef : string
    +reactionRef : string
    condition : string
  }

  %% ─── Feature Children ────────────────────────────────────────────────────────

  class criteria
  class requirement {
    +id : string
    priority : must|should|could|wont
    tags : string
  }
  class criterion {
    +id : string
    ref : string
    scope : string
  }

  %% ─── Blueprint Children ──────────────────────────────────────────────────────

  class approach {
    +label : string
  }
  class component {
    +id : string
    +layer : controller|service|repository|worker|gateway|store|util|ui|adapter|infrastructure|orchestrator|contract
    tech : string
  }
  class uses {
    +ref : string
  }
  class rule {
    +id : string
    +force : must|should
    +ref : string
  }
  class BPLink["link"] {
    ref : string
    url : string
  }

  %% ─── Manifest Children ───────────────────────────────────────────────────────

  class value {
    +id : string
    +label : string
  }
  class principle {
    +id : string
    +label : string
  }
  class goal {
    +id : string
    +label : string
    status : pending|achieved
  }

  %% ─── Milestone Children ──────────────────────────────────────────────────────

  class includes {
    +ref : string
  }

  %% ─── Flow Children ───────────────────────────────────────────────────────────

  class precondition
  class postcondition {
    outcome : string
  }
  class step {
    action : string
    actor : string
  }
  class branch {
    +condition : string
  }
  class path {
    +outcome : string
    label : string
    emit : string
    throws : string
  }

  %% ─── Tour Children ───────────────────────────────────────────────────────────

  class stop {
    +surface : string
    +title : string
    transition : none|fade|slide|slide-back
    duration : number
    scale : number
  }
  class spotlight {
    +target : string
    type : ring|pulse|dim|highlight
    duration : number
    seq : number
  }
  class overlay {
    +target : string
    anchor : top|right|bottom|left
    seq : number
  }

  %% ─── Surface / UI Children ───────────────────────────────────────────────────

  class interactions {
    +id : string
    +start : string
  }
  class clickable {
    +from : string
    +target : string
    transition : none|fade|slide|slide-back
  }

  %% ─── Changeset Children ──────────────────────────────────────────────────────

  class touched {
    +ref : string
  }

  %% ─── Composition: domain ─────────────────────────────────────────────────────
  domain *-- tldr
  domain *-- explanation
  domain *-- diagram
  domain *-- setting
  domain *-- glossary
  domain *-- model
  domain *-- api
  domain *-- policy
  glossary *-- term

  %% ─── Composition: feature ────────────────────────────────────────────────────
  feature *-- tldr
  feature *-- explanation
  feature *-- diagram
  feature *-- setting
  feature *-- api
  feature *-- requirement
  feature *-- criteria
  feature *-- interactions
  criteria *-- criterion

  %% ─── Composition: role ───────────────────────────────────────────────────────
  role *-- tldr

  %% ─── Composition: flow ───────────────────────────────────────────────────────
  flow *-- tldr
  flow *-- explanation
  flow *-- precondition
  flow *-- postcondition
  flow *-- step
  step *-- branch
  branch *-- path

  %% ─── Composition: manifest ───────────────────────────────────────────────────
  manifest *-- tldr
  manifest *-- value
  manifest *-- principle
  manifest *-- goal
  manifest *-- requirement

  %% ─── Composition: blueprint ──────────────────────────────────────────────────
  blueprint *-- tldr
  blueprint *-- explanation
  blueprint *-- diagram
  blueprint *-- approach
  blueprint *-- component
  blueprint *-- rule
  blueprint *-- BPLink
  component *-- uses

  %% ─── Composition: story ──────────────────────────────────────────────────────
  story *-- tldr
  story *-- interactions

  %% ─── Composition: milestone ──────────────────────────────────────────────────
  milestone *-- tldr
  milestone *-- includes

  %% ─── Composition: tour ───────────────────────────────────────────────────────
  tour *-- tldr
  tour *-- stop
  stop *-- spotlight
  stop *-- overlay

  %% ─── Composition: surface ────────────────────────────────────────────────────
  surface *-- interactions
  interactions *-- clickable

  %% ─── Composition: changeset ──────────────────────────────────────────────────
  changeset *-- touched

  %% ─── API internals ───────────────────────────────────────────────────────────
  api *-- action
  api *-- event
  api *-- operation
  api *-- error
  action *-- property
  event *-- property
  operation *-- property
  operation *-- returns
  operation *-- throws
  returns *-- property

  %% ─── Cross-doc references ────────────────────────────────────────────────────
  feature ..> domain : domains=
  feature ..> role : roles=
  story ..> role : role=
  story ..> feature : features=
  tour ..> feature : feature=
  surface ..> feature : feature=
  blueprint ..> feature : implements=
  includes ..> feature : ref=
  criterion ..> requirement : ref=
  throws ..> error : ref=

  %% ─── Styling ─────────────────────────────────────────────────────────────────
  classDef root fill:#1e3,stroke:#4a90d9
  

  %% ─── Links to instruction pages ──────────────────────────────────────────────
  link domain "/starspec/tag/domain"
  link feature "/starspec/tag/feature"
  link role "/starspec/tag/role"
  link flow "/starspec/tag/flow"
  link manifest "/starspec/tag/manifest"
  link blueprint "/starspec/tag/blueprint"
  link story "/starspec/tag/story"
  link milestone "/starspec/tag/milestone"
  link tour "/starspec/tag/tour"
  link surface "/starspec/tag/surface"
  link changeset "/starspec/tag/changeset"
  link tldr "/starspec/tag/tldr"
  link explanation "/starspec/tag/explanation"
  link diagram "/starspec/tag/diagram"
  link setting "/starspec/tag/setting"
  link api "/starspec/tag/api"
  link action "/starspec/tag/api"
  link event "/starspec/tag/api"
  link operation "/starspec/tag/operation"
  link error "/starspec/tag/error"
  link throws "/starspec/tag/throws"
  link returns "/starspec/tag/returns"
  link property "/starspec/tag/property"
  link glossary "/starspec/tag/glossary"
  link term "/starspec/tag/glossary"
  link model "/starspec/tag/model"
  link policy "/starspec/tag/policy"
  link requirement "/starspec/tag/requirement"
  link criteria "/starspec/tag/criterion"
  link criterion "/starspec/tag/criterion"
  link approach "/starspec/tag/blueprint"
  link component "/starspec/tag/blueprint"
  link uses "/starspec/tag/blueprint"
  link rule "/starspec/tag/blueprint"
  link BPLink "/starspec/tag/blueprint"
  link value "/starspec/tag/manifest"
  link principle "/starspec/tag/manifest"
  link goal "/starspec/tag/manifest"
  link includes "/starspec/tag/milestone"
  link precondition "/starspec/tag/flow"
  link postcondition "/starspec/tag/flow"
  link step "/starspec/tag/flow"
  link branch "/starspec/tag/flow"
  link path "/starspec/tag/flow"
  link stop "/starspec/tag/tour"
  link spotlight "/starspec/tag/tour"
  link overlay "/starspec/tag/tour"
  link interactions "/starspec/tag/interactions"
  link clickable "/starspec/tag/interactions"
  link touched "/starspec/tag/touched"

Examples — well-formed document samples

Type	Instruction path
Domain	starspec/authoring/examples/domain
Feature	starspec/authoring/examples/feature
Flow	starspec/authoring/examples/flow
UI	starspec/authoring/examples/surface
Story	starspec/authoring/examples/story
Manifest	starspec/authoring/examples/manifest
Brainstorm output	starspec/authoring/examples/brainstorm

Compiler evolution — modifying StarSpec itself

Intent	Instruction path
Design loop for evolving the compiler	starspec/extend-starspec
Implementation checklist for adding a tag	starspec/adding-a-tag
Sidebar configuration & entry ID reference	starspec/sidebar-config
Compiler architecture end-to-end	starspec/architecture
Fragment system	starspec/fragments

Wireframe / UI design system

Intent	Instruction path
Wireframe CSS and theming overview	starspec/wireframe/css
Author a new wireframe theme	starspec/wireframe/theming
Theme TOML manifest specification	starspec/wireframe/theme-toml
UI DSL component reference	starspec/agents/conventions/surface-dsl

Agent loops

Agent	Instruction path
StarVision — extract wireframe theme from screenshots	starspec/agents/starvision/theme.extract

Consumer agent reference

Intent	Instruction path
Query routing for implementation agents	starspec/consumer
Aggregate bundle index	starspec/agents/common/bundle-paths

Release & Deployment

Intent	Instruction path
Build, test, and deploy the docs site with Docker / Coolify	starspec/release

Shared reference fragments

Fragment	Instruction path
Command routing table (starscribe + stardesign + starfix)	starspec/agents/common/command-routing
Tag inventory (all tags with parent and description)	starspec/fragments/tags/inventory
Tag ER diagram (all tags, attributes, relationships)	starspec/fragments/tags/er-diagram
Naming conventions and audit loop	starspec/agents/conventions/naming-standards
Scope rules	starspec/fragments/compiler/scope-rules
MCP server policy	starspec/agents/common/mcp-policy
Test and verification commands	starspec/agents/starspec/test-suite
Documentation update checklist	starspec/agents/starspec/update-checklist
Aggregate bundle paths	starspec/agents/common/bundle-paths
TagProcessor interface	starspec/fragments/compiler/processor-api
Content folder layout	starspec/fragments/compiler/content-layout
Compiler source layout	starspec/fragments/compiler/source-layout
Tag documentation guide	starspec/fragments/compiler/tag-documentation
Visual regression testing	starspec/agents/starspec/visual-regression
Wireframe theme variable reference	starspec/fragments/wireframe/theme-variables
Wireframe theme selector pattern	starspec/fragments/wireframe/theme-selector-pattern
Wireframe CSS conventions	starspec/fragments/wireframe/css-conventions

Documentation Inventory

Page	Description
Adding a Tag	Step-by-step guide for extending StarSpec with a new Markdoc tag or document type
Aggregate Bundles	Index of pre-compiled system-wide data bundles for agents
Command Routing	Maps agent user commands to instruction paths
MCP Server Policy	Fail-early rules, disk fallback convention, and error handling cascade for MCP server availability
Starscribe User Guide	How to interact with the Starscribe agent — commands, workflows, and tips for getting the best results
File Conventions	File patterns, folder paths, workflow naming conventions, and canonical verbs for all StarSpec document and workflow types
Frontmatter Reference	Complete field table for all StarSpec document frontmatter blocks
Naming Conventions for Memo Preprocessing	Compact naming reference for actions, events, operations, errors, and entities used during memo-to-prespec extraction
Naming Conventions	Id naming rules for all StarSpec documents and tags
UI DSL Reference	Comprehensive index of all available components in the Pug-based UI DSL
UI Design Principles	Authoring rules for surface documents — component semantics, accessibility, feature linkage, layout hierarchy, placeholder discipline
Viewer Chrome — Starlight CSS Gotchas	Rules for .not-content class and flex alignment on chrome elements inside Starlight pages
Writing Principles	Authoring rules that apply to all StarSpec document types regardless of active workflow
StarDesign Agent	Specialized UI design agent for StarSpec. Authors surface documents using the Pug DSL and links wireframes to features and flows.
Interactive Prototype Flows	How to author interactions/clickable tags for linking surfaces into clickable navigation prototypes
Sketch Import Loop	Converts hand-drawn or schematic sketches into DSL surface documents using multimodal vision
Audit a UI Surface	Quality checklist for reviewing a surface document before status promotion
Create a UI Surface	Design loop for creating a new UI surface document using the Pug DSL
Extend a UI Surface	How to iterate on an existing surface document — add components, revise layout, or update interactive structure
Autonomous Visual Feedback Loop	Screenshot capture and multimodal verification loop for iterating on CSS and DSL changes
StarFix Agent	Convention enforcement and validation agent. Detects and fixes schema errors, semantic model issues, and naming violations across all StarSpec documents.
Model Sanitization Workflow	Detect and fix semantic model quality issues — wrong tag types, missing structured links, incorrect id formats
Lint & Fix Workflow	Detect, classify, and fix schema validation errors reported by the compiler
StarMemo Agent	Preprocessing agent that converts raw application memos (transcripts, prose notes) into a structured PreSpec document, then runs an interactive clarification loop before handing off to starscribe scaffold mode.
Memo Clarification Loop	Seven-round interactive clarification loop for PreSpec documents — gap taxonomy, proposal rules, and structured question bundling
StarScribe Agent	Specialized authoring agent for StarSpec documents. Fetches design loops and tag schemas dynamically from the StarSpec MCP server via get_instructions.
API Audit Workflow	Uses the action/event/operation perspective as primary lens for building and improving specs — inventories behavioral surface, finds gaps, derives new API items from flows, surfaces, requirements, and stories
Design creation	Design loop for producing one or more architecture or implementation design documents from existing specifications
Brainstorm Session	Design loop for capturing a new initiative and producing manifest documents and a suggested backlog
Changeset creation	Design loop for documenting a batch of specification changes
Scaffold Mode — Import an Application Description	Bootstraps a full StarSpec content tree from a single Markdown file describing an application in semi-structured prose
Domain creation	Design loop for creating a new domain document
Domain extension	How to add models, actions, events, or glossary terms to an existing domain
Feature creation	Design loop for creating a new feature document
Feature extension	How to add requirements, flows, criteria, or API entries to an existing feature
Flow creation	Design loop for creating a standalone flow document
Manifest creation	Design loop for creating a targeted manifest document
Milestone creation	Design loop for creating a versioned release milestone
Role creation	Design loop for creating a new role document
Role extension	How to update an existing role definition with new responsibilities, feature links, or access constraints
Story creation	Design loop for creating a user story document
Transcript Import Workflow	Preprocesses a conversation transcript into a structured intermediate document aligned to the StarSpec metamodel — deduplicates, extracts structure, flags inconsistencies
StarSpec Agent	Entry point agent for the StarSpec specification compiler. Handles compiler modifications, tag additions, scaffold mode, documentation improvements, and agent workflow authoring.
Test Commands	The three-step verification sequence required after any compiler change
Documentation Update Checklist	Items to verify before closing any StarSpec compiler modification task
Visual Regression Testing	How to capture, compare, and promote component screenshots across the full dimension matrix
Agent Workflow Authoring	Workflow for creating, extracting, and modifying agent workflow fragments and agent definitions
Starticle Agent	Article authoring agent — drafts, researches, and reviews long-form prose articles using the full article tag vocabulary (atoms, citations, footnotes, quotes, callouts, carousels).
Article Review Workflow	Structured review of an existing article against quality criteria, tag usage, and optional user-specified focus
Article Draft Workflow	Multi-phase workflow for drafting a new article from an input document, audio transcript, or prompt — with emphasis on structured tag usage and knowledge extraction
Style Rewrite Workflow	Rewrites an existing article to conform to a selected style guide (prose or scientific) while retaining all information. Style changes are applied directly; structural changes require user approval.
Elements of Style — Prose	Style rules for general prose writing, adapted from Strunk (1918). Used by the article.rewrite workflow to evaluate and rewrite articles targeting a prose voice.
Elements of Style — Scientific	Style rules for scientific writing and journalism, adapted from Strunk (1918). Used by the article.rewrite workflow to evaluate and rewrite articles targeting a scientific voice.
StarVision Agent	Specialized Design System agent for StarSpec. Extracts wireframe themes from visual assets (screenshots, PDFs) and textual guidelines into CSS tokens and TOML manifests.
StarVision Theme Extraction	Instruction loop for extracting wireframe themes from visual assets
Architecture	How StarSpec compiles .mdoc source files into TOON bundles and a Starlight documentation site
Authoring Blueprints	Conceptual guide to architectural design documents
Authoring Domains	Conceptual guide to bounded context modelling in StarSpec
Brainstorm Example	Example output of a completed brainstorm session
Domain Example	Sample well-formed domain document
Feature Example	Sample well-formed feature document
Flow Example	Sample well-formed flow document
Manifest Example	Example of a complete manifest document
Story Example	Example of a complete user story document
UI UI Example	A well-formed example of a .ui.mdoc file using the Pug DSL
Authoring Features	Conceptual guide to specifying user-facing capabilities
Authoring Flows	Conceptual guide to step-by-step interaction sequences
Authoring Manifests	Conceptual guide to capturing project identity and non-functional requirements
Authoring Milestones	Conceptual guide to versioned release planning
Authoring Roles	Conceptual guide to defining actors and their responsibilities
Authoring Stories	Conceptual guide to narrative walkthroughs linking roles to features
Authoring Surfaces	Conceptual guide to UI wireframe specification in Pug DSL
Extend StarSpec	Design loop for adding a new tag to the StarSpec compiler
Fragments — Reusable Content Fragments	How the include directive system works and when to use it
Content Layout	Source folder structure for StarSpec content files
TagProcessor Interface	The TagProcessor interface, declarative properties, render() signature, and bundle placement rules
Scope Rules	How scope propagation works and how to filter by scope in processors
Compiler Layout	packages/compiler/src directory structure and key file roles
Documenting a Tag	How to write a *.tag.mdoc file that describes a StarSpec Markdoc tag — structure, conventions, and checklist
Tag ER Diagram	Complete Mermaid class diagram of all StarSpec tags with attributes and containment relationships — click any node to open its instruction page
Tag Inventory	Complete list of all StarSpec Markdoc tags with one-line descriptions
button-group	Button groups are used to group related buttons into sections.
button	Action buttons with semantic variants, sizes, appearance styles, and icon support.
floatbutton	Floating Action Button (FAB) anchored to a corner of the screen.
chart	Visual data representations — radial, area, and bar chart variants.
format	Format utilities for numbers, dates, and byte sizes using browser-native Intl APIs.
list	Simple vertical collection with bullet, ordered, or plain marker styles.
progress	Linear and circular progress indicators — progress-bar and progress-ring components.
qr-code	QR code generator rendered via the Canvas API with size, radius, and error-correction options.
relative-time	Outputs a localized time phrase relative to the current date and time.
stat-card	Dashboard KPI metric card with value, label, and trend indicator.
table	Tabular data display with configurable columns, striped rows, and row count.
timeline	Vertical chronological sequence of events with status and icon markers.
alert	Contextual feedback messages with info, success, warning, and error variants.
animated-image	Displays an image that can be paused and played.
animation	Provides a declarative way to create animations.
avatar	Avatars represent a person or object.
badge	Badges are used to draw attention and display statuses or counts.
callout	Callouts are used to display important messages inline.
chat-bubble	Conversational message layout with sent/received alignment and status indicators.
heading	Visual hierarchy markers for screen titles and section headers.
icon	Icons are symbols representing options or states.
spinner	Indeterminate progress indicator.
tag	Tags are used as labels to organize things or to indicate a selection.
text	Body copy and descriptive text with size and muted variants.
typing-dots	Animated conversational activity indicator shown while the other party is typing.
checkbox	Checkboxes allow the user to toggle an option on or off.
color-picker	Color pickers allow the user to select a color.
datepicker	Calendar-based date selection input.
input	Inputs collect data from the user.
otp-field	Specialized multi-box input for verification codes and PINs.
radio-group	Groups multiple radio buttons.
radio	Mutually exclusive selection. Use inside a radio-group.
rating	Ratings give users a way to quickly view and provide feedback.
segmented	A row of mutually exclusive toggle buttons (segmented control).
select	Dropdown selection menu with search and adaptive (bottom-sheet) modes.
slider	Ranges allow the user to select a value within a range.
switch	Binary toggle switch.
textarea	Textareas collect data from the user and allow multiple lines of text.
card	Contained content block with padding, optional elevation, appearance variants, and orientation.
divider	Dividers are used to visually separate or group elements.
grid	Creates a multi-column grid layout with configurable column count and gap.
phone-shell	Renders the outline of a physical phone and places its child content on the screen.
row	Organizes children in a horizontal line with configurable gap, justify, and alignment.
scroller	Accessible scrollable container with visual edge cues.
section	Full-width page container with a dashed wireframe border; outermost shell of a screen.
stack	Organizes children in a vertical column with configurable gap and alignment.
accordion / panel	Collapsible content panels. DSL alias panel maps to wa-details.
breadcrumb	Breadcrumbs provide a group of links so users can easily navigate a hierarchy.
dialog / modal	Interruptive overlay dialog. DSL alias modal maps to wa-dialog.
drawer	Sliding overlay panel.
dropdown-item	Individual item within a dropdown menu.
dropdown	Contextual list of options triggered by a button.
link	Navigation link used inside nav, breadcrumb, and menu components.
menu	Command or context menus with dropdown and inline list variants.
nav	Application navigation shell — top bar, sidebar, or breadcrumb. Contains link children.
pagination	Renders a page-navigation control with prev/next buttons, numbered page buttons, ellipsis gaps, and a results summary.
stepper	A linear sequence of steps for multi-step workflows.
tab-group	Tab groups organize content into distinct tabbed views.
tabs	Switches between mutually exclusive content panels using tab headers.
tree	Hierarchical collapsible tree with selectable items.
Action Panel	Vertical stack of primary and secondary action buttons in an elevated card.
Activity Log	Chronological event feed using timeline inside an elevated card with item count badge.
Comments	Comment thread with inline comment cards and a textarea compose area.
Data Display	KPI stat-card grid combined with an area chart trend card.
Description List	Key-value detail rows separated by dividers inside an elevated card.
Empty State	Centered icon, heading, muted message, and a primary action for zero-result screens.
FAQ	Expandable FAQ list using accordion panels inside a card.
Grid List	Header row with new-item button over a 3-column card grid with status badges.
Leaderboard	Ranked list of contributors with position badge and point total.
Pagination	Striped table with a results count and prev/next page button row.
Change Password	Password change form with current/new/confirm inputs, info alert, and action buttons.
Permissions Table	Role-based permission matrix using a multi-column striped table.
Pricing	3-column pricing tier grid with highlighted recommended plan and CTA buttons.
Banner	Full-width info alert used as a site-wide announcement banner.
Call to Action	Centered hero CTA with heading, muted subtext, and primary + ghost button row.
Category List	Icon + label rows with article count badges for browsing content by topic.
Contact	2-column contact card with form inputs on the left and contact info on the right.
Featured Post	Hero card with cover image, category badge, title, byline, excerpt, and read CTA.
Footer	4-column site footer with nav link lists, newsletter signup, divider, and legal row.
Grid Sections	Centered section heading with a 3-column icon + title + description feature grid.
Newsletter Signup	Centered newsletter card with icon, heading, email input, and no-spam note.
Paywall	Article limit banner with free vs. pro plan comparison and upgrade CTA.
Post Footer	Author bio card and related articles grid below an article divider.
Post Header	Article header with category badges, title, publish date, cover image, and author row.
Post List	Article list with thumbnail, category badge, title, and read-time meta per card.
Sign Up & Login	Auth card with email/password inputs, remember-me checkbox, forgot password, and OAuth button.
Site Header	Blog/marketing site header with brand, ghost nav links, search input, and subscribe CTA.
Social Share	Article sharing bar with platform buttons and a copy-link ghost button.
Stats & Numbers	4-column grid of large headline numbers with muted labels for social proof.
Teams	3-column team member grid with photo placeholder, name, role, and social link.
Testimonials	2-column quote cards with star icons and avatar + name attribution.
Category Filter	Product filter sidebar with checkbox categories, price range inputs, and rating filters.
Category Preview	4-column grid of category cards with image placeholder and bold label.
Checkout Form	Multi-step checkout with stepper progress, shipping address form, and back/continue actions.
Incentives	3-column icon + label trust bar for shipping, returns, and support reassurances.
Order History	List of past orders with order ID, date, total, status badge, and view/track action.
Order Summary	Cart summary card with line items, subtotal/shipping/discount rows, and promo code input.
Product List	3-column product grid with image, name, price, and add-to-cart button; includes search and filter bar.
Product Overview	2-column product detail with image gallery, variant selectors, add-to-cart, and accordion details.
Product Preview	Compact 2-column product card with image, badge, name, price, variant selector, and CTA.
Product Reviews	Review summary with aggregate rating, progress-bar breakdown per star, and individual review cards.
Shopping Cart	Cart panel with item rows (thumbnail, name, quantity, price, remove), total, and checkout button.
Store Navigation	E-commerce header with brand, category nav buttons, search input, account, and cart.
Form Shell	Form screen layout with title, card containing inputs, and a submit button.
Checkout Layout	Full-page 2-column checkout with stepper + shipping form on the left and order summary on the right.
Dashboard Layout	Full-page analytics dashboard with header, 4-column KPI row, 2-column charts, and data table.
Blog Listing Layout	Full-page blog listing with filter tabs, featured hero article, and 3-column post grid.
Personal Details Layout	4-column account settings layout with sidebar nav and stacked profile, password, and sessions cards.
Product Overview Layout	Full-page product detail with 2-column image + selectors, accordion details, and reviews section.
Settings Layout	4-column settings page with sidebar nav, general preferences card, and danger zone card.
Storefront Layout	Full e-commerce homepage with nav, hero banner, incentives bar, category grid, product grid, and newsletter.
Transactions Layout	Full-page transaction list with filter bar (search, status, date range), paginated table, and export action.
List Shell	List screen layout with header, search input, and card-based list items with badges.
Screen Shell	Full screen layout with header row, primary card section, and secondary card section.
Settings Shell	Settings screen layout with a preferences card containing divider-separated rows of controls.
placeholder	Generic content placeholder for undesigned layout areas, with type and sizing options.
skeleton / placeholder	Loading skeleton placeholders with pulse and sheen animation effects. placeholder is an alias.
carousel-item	Individual slide in a carousel.
carousel	Displays content slides along an axis.
comparison	Compare two images or content regions with a draggable divider.
zoomable-frame	Zoomable container.
UI CSS Conventions	BEM naming and variable system for wireframe styling
Wireframe Theme Selector Pattern	Copy-paste CSS selector template for StarSpec wireframe themes — light/dark compound selectors with specificity notes
Base Theme Variable Reference	Complete set of CSS variables every StarSpec wireframe theme must implement, organized by category
Release & Deployment	How to build, test, and deploy the StarSpec documentation site and MCP server using Docker Compose and Coolify
Sidebar Configuration	How to configure the sidebar in starspec.config.js — entry IDs, sections, groups, and ordering
{% action %}	{% action %}
{% api %}	{% api %}
{% approach %}	{% approach %}
{% article %}	{% article %}
{% asset %}	{% asset %}
{% atom %}	{% atom %}
{% bibliography %}	{% bibliography %}
{% blueprint %}	{% blueprint %}
{% branch %}	{% branch %}
{% callout %}	{% callout %}
{% carousel %}	{% carousel %}
{% changeset %}	{% changeset %}
{% citation %}	{% citation %}
{% cite %}	{% cite %}
{% clickable %}	{% clickable %}
{% component %}	{% component %}
{% concept %}	{% concept %}
{% criteria %}	{% criteria %}
{% criterion %}	{% criterion %}
{% diagram %}	{% diagram %}
{% domain %}	{% domain %}
{% emits %}	{% emits %}
{% error %}	{% error %}
{% event %}	{% event %}
{% example %}	{% example %}
{% explanation %}	{% explanation %}
{% feature %}	{% feature %}
{% flow %}	{% flow %}
{% phase %}	{% phase %}
{% footnote %}	{% footnote %}
{% glossary %}	{% glossary %}
{% goal %}	{% goal %}
{% implements %}	{% implements %}
{% includes %}	{% includes %}
{% interactions %}	Schema and usage rules for interactive prototype flows
{% interactions %}	{% interactions %}
{% listens %}	{% listens %}
{% manifest %}	{% manifest %}
{% marker %}	{% marker %}
{% milestone %}	{% milestone %}
{% model %}	{% model %}
{% operation %}	{% operation %}
{% overlay %}	{% overlay %}
{% path %}	{% path %}
{% policy %}	{% policy %}
{% postcondition %}	{% postcondition %}
{% precondition %}	{% precondition %}
{% principle %}	{% principle %}
{% property %}	{% property %}
{% prose %}	{% prose %}
{% quote %}	{% quote %}
{% requirement %}	{% requirement %}
{% returns %}	{% returns %}
{% role %}	{% role %}
{% rule %}	{% rule %}
{% setting %}	{% setting %}
{% slide %}	{% slide %}
{% smartag %}	{% smartag %}
{% spotlight %}	{% spotlight %}
{% step %}	{% step %}
{% stop %}	{% stop %}
{% story %}	{% story %}
{% surface %}	{% surface %}
{% tag %}	{% tag %}
{% term %}	{% term %}
{% throws %}	{% throws %}
{% timeline %}	{% timeline %}
{% tldr %}	{% tldr %}
{% touched %}	{% touched %}
{% tour %}	{% tour %}
{% uses %}	{% uses %}
{% value %}	{% value %}
Wireframe CSS	Documentation for the StarSpec wireframe styling system and how to author new wireframe themes
Full Theme Guide	How to create a new StarSpec wireframe design-system theme — CSS file, selector pattern, dark/light support, and registration
Theme TOML Specification	Full specification for the StarSpec wireframe theme manifest (theme.toml) — wf-* variable layer only
Authoring Wireframe Themes	How to create a new StarSpec wireframe design-system theme — CSS file, selector pattern, dark/light support, and registration