Design System

Reusable demo components, documentation patterns and real CSS scenarios for the Master CSS site.

A shared visual language for explaining CSS. Quiet surfaces, precise annotations, and real browser behavior give every example a clear purpose.

Foundations

The canvas establishes context. Blue identifies the subject; violet identifies a comparison; neutral surfaces support the example without competing with it. All roles adapt to light and dark themes.

Use the preset spacing, radius and typography scales. Demo-specific roles live in the site theme: demo-canvas, demo-surface, demo-line, demo-grid, demo-text, demo-muted, demo-blue, demo-violet, demo-amber, and demo-neutral.

Demo canvas

Demo uses the site's neutral fine diagonal stripe by default, matching the established Guide canvas. The shell supplies a border and responsive breathing room, while the example supplies its own layout and geometry. A title, description, controls, and caption appear only when the lesson needs them; controls remain outside the demonstrated layout.

<Demo>  <div className="flex gap-sm">    <DemoItem className="p-md">01</DemoItem>    <DemoItem className="p-md">02</DemoItem>  </div></Demo>

Use padding="none" for an iframe or a scene with its own spacing. background="plain", "grid", "dots", and "checkerboard" are opt-in when a lesson needs an unpatterned surface, geometry grid, or transparency cue. Do not put labels or toolbar controls inside a measured flex, grid, or float scene. The live clear reference demonstrates an isolated iframe with a caption; the spacing guide retains its original pink inner stripe where that pattern explains padding and gap.

Primitives

Compose small, predictable pieces. An item supplies its appearance; the example supplies its layout and dimensions.

Content specimens

TEXT

Form follows function.

Use meaningful content to make layout decisions visible.

MEDIA

Demo surface

DemoSurface keeps content legible on the striped canvas with a fine border, a compact radius and the site's raised surface color. It adds no padding, dimensions, layout, clipping or shadow by default. Use elevation="raised" only when the lesson needs to show a floating layer; it adds the preset's small shadow without changing the content box.

<DemoSurface className="p-md">A quiet content surface.</DemoSurface><DemoSurface elevation="raised" className="p-md">A floating layer.</DemoSurface>

The column span reference keeps columns and padding inside the default surface; the float reference supplies its own flow-root boundary. The original Guide panel remains in its established examples. Place any label or control outside a measured flex, grid or float layout unless it is part of the lesson.

Demo item

DemoItem starts as a neutral raised surface with a crisp border. Set tone="blue" to identify the subject or tone="violet" for a comparison. The optional soft, solid, outline, and ghost variants change paint only. The item has no implied width, height, padding, layout, position, or interactive behavior; the lesson supplies those explicitly.

<Demo>  <div className="flex gap-sm">    <DemoItem className="p-md">Context</DemoItem>    <DemoItem tone="blue" className="p-md">Subject</DemoItem>  </div></Demo>

The order reference marks the reordered item in blue. The column span reference uses the same explicit subject tone, while the spacing guide keeps its original object and pink inner stripe. DemoItem renders a noninteractive div; use a native button or link when a specimen performs an action.

Demo text

DemoText renders a native paragraph. Its default body role inherits the surrounding font size and keeps the existing margin reset and 1.65 line height, so text-flow lessons retain their geometry. Opt into variant="lead" for prominent specimen copy or variant="caption" for a short note; these roles supply type treatment without becoming extra layout items.

<DemoText variant="lead">A clear specimen heading.</DemoText><DemoText>Explanatory copy inherits its container size.</DemoText><DemoText variant="caption">Condition: narrow viewport.</DemoText>

Utilities on className can override these paint and typography defaults when the text property itself is under test. The float reference uses default body text beside an actual floated image. The typography guide retains its original DemoP comparison for the lesson on the text scale.

Demo media

DemoMedia renders a refined SVG specimen when no source is supplied. Its quiet contour artwork follows currentColor so a complete utility such as fg-demo-violet can mark a comparison. With src and required alt, it renders the supplied image instead. Both forms have a fine visual edge that takes no layout space.

<DemoMedia className="w:100% r-sm" aria-label="Sun above two mountain ridges" /><DemoMedia src="/demo/landscape.svg" alt="Sun above layered mountains" width={320} height={200} />

The caller sets width, height, crop, float and spacing. The float reference demonstrates a real floated image; the introduction guide retains its original architectural photograph where content, rather than a placeholder, is the point.

Demo swatch

DemoSwatch is a static inventory tile for semantic color roles. Its restrained frame keeps pale canvas and surface colors visible next to saturated subject and comparison colors. label is required; optional value names the token or value in a compact monospace line. An explicit utility class or style supplies the actual color.

<DemoSwatch label="Subject" value="demo-blue" className="bg-demo-blue" />

The color patch is decorative when it has no children, while the visible label carries the meaning. This tile has no copy action or focus stop. The colors guide retains its original interactive palette for browsing and copying fixed color steps.

Demo comparison

DemoComparison arranges direct children in responsive columns. The adopted layout gives each specimen a 17rem reading minimum and uses the site's large spacing step between columns. The specimens stack when there is not enough room for both; the wrapper adds no frame, padding, labels or paint. Give each child its own dimensions and utilities so the comparison shows the actual property under discussion.

<Demo>  <DemoComparison>    <DemoSurface className="p-md">Before</DemoSurface>    <DemoSurface elevation="raised" className="p-md">After</DemoSurface>  </DemoComparison></Demo>

The “Content specimens” and “Comparison” examples above use this layout. The elevation guide retains its original spacious comparison grid, while the comparison review shows that grid beside the previous and adopted shared treatments. Place comparison labels outside any measured flex, grid or float scene.

DemoBadge labels a state or category. It renders a native span with four sizes (xs, sm, md, lg), the shared tones and the same paint variants as DemoItem. The default is a neutral, soft, medium badge. Its compact radius, tabular monospace text and font-relative padding are explicit; keep badges outside measured layouts unless their dimensions are part of the lesson. Use a native button when the label performs an action. The badge review compares the Guide label, earlier badge and adopted treatment.

<DemoBadge tone="blue" size="sm">Selected layer</DemoBadge>

<Demo title="Alignment" background="grid">  <div className="flex items-center gap-sm">    <DemoItem className="p-md">01</DemoItem>    <DemoItem tone="violet" className="p-md">02</DemoItem>  </div></Demo>

Downloadable assets

DemoAsset pairs original artwork with a named surface and a native download link. Use it for logos, icons or exported diagrams; it is a presentation frame, not a measured CSS layout. Intrinsic image dimensions reserve the aspect ratio. The preview constrains images to the available width and a 6rem height without cropping. The image remains transparent over the chosen preview surface in either page theme.

Master CSS mark

Transparent is the default surface.

SVGDownload SVG

<DemoAsset  title="Master CSS mark"  description="Original SVG artwork."  src="/images/logo.svg"  alt="Master CSS gold mark"  width={104}  height={56}/>

Use surface="light" or surface="dark" to keep the preview background fixed across page themes. surface="transparent" uses a checkerboard. The footer stays outside the artwork and exposes the file format (SVG by default). Use same-origin URLs for native downloads and a descriptive title for each accessible download name. See the Brand page for the light, dark and transparent variants together, and the asset review for original, previous and adopted treatments.

Annotations

Name the subject, reveal a boundary, or expose an axis. Keep annotations outside the layout being demonstrated. Use color with labels, never as the only explanation.

DemoMeasure observes its content boundary and updates as the container changes. DemoAxes and DemoLegend describe the relationship without inserting items into the measured flex or grid parent.

Demo label

DemoLabel identifies a class, object or condition with a compact monospace line. The adopted treatment is a little larger and clearer than the earlier shared label, with tabular numerals and wrapping for long utilities. It adds no background, border or spacing; the scene sets the distance to its subject.

<div>  <DemoLabel>shadow-sm</DemoLabel>  <DemoSurface className="mt-xs p-md">Standard surface</DemoSurface></div>

Keep a label outside the measured flex or grid parent unless it is part of the layout lesson. The elevation guide retains its original labels, and the label review shows those beside the previous and adopted shared styles.

Demo legend

DemoLegend is a separate key for recurring color roles. Each item pairs a short name with a small bordered swatch, and the list wraps as space narrows. Its compact monospace text follows the shared label scale; the swatches are decorative, so the names carry the meaning. Place the legend in the demo caption or beside its description, outside the measured layout.

<Demo caption={<DemoLegend items={[  { tone: 'blue', label: 'Subject border' },  { tone: 'violet', label: 'Comparison border' },]} />}>  {/* The lesson's two border specimens live here. */}</Demo>

Include only roles visible in the scene. The border color reference labels its blue and violet specimens directly; the legend review compares that teaching pattern with the previous and adopted shared keys.

Demo measure

DemoMeasure observes the rendered content boundary and displays its width and height in pixels. The adopted annotation separates the name from the numeric readout, with a fine ruler spanning the observed wrapper. It updates when the available width or the content height changes; a requested CSS width can differ from the measured width inside a narrow column.

<DemoMeasure label="Content bounds">  <DemoSurface className="p-md">Measured content</DemoSurface></DemoMeasure>

Place the measurement wrapper outside the flex, grid or float parent being taught, so it does not become an extra layout item. The width reference reports the actual browser geometry for its examples. The measure review tests live width and height changes beside the original Guide layout ruler.

Demo axes

DemoAxes puts a labeled horizontal rule and vertical rule around one example. Its default main-axis arrow points right and its cross-axis arrow points down, matching a left-to-right row in horizontal writing. The rules are decorative; the text supplies the axis names. The adopted treatment gives the labels a clear monospace scale and keeps both rules outside the example's flex layout.

<DemoAxes aria-label="Row layout: main axis rightward, cross axis downward">  <div className="flex gap-sm">{/* layout items */}</div></DemoAxes>

Use this frame only when those physical directions match the specimen; reverse and vertical examples need annotations that follow their actual directions. The flex direction reference shows the real row behavior, and the axes review compares the original Guide labels with the previous and adopted frame.

Interaction

Add controls when they help explain a change. Static specimens have no toolbar. Playback-controlled specimens start paused; bounded scroll areas remain keyboard accessible.

Demo controls

DemoControls is a fieldset with an accessible group name. Its plain default leaves mixed sliders, action buttons and print controls ungrouped. For a small set of exclusive choices, use variant="segmented": the selected native button has a separate surface and keeps aria-pressed, while a visible focus outline supports keyboard use. Both appearances stay outside the layout being demonstrated.

<DemoControls label="Cross-axis alignment" variant="segmented">  <button type="button" className="demo-button" aria-pressed={alignment === 'items-start'}>Start</button>  <button type="button" className="demo-button" aria-pressed={alignment === 'items-center'}>Center</button>  <button type="button" className="demo-button" aria-pressed={alignment === 'items-end'}>End</button></DemoControls>

The controls review compares both shared appearances with the original Syntax Tutorial viewport switch, which retains its own controls.

Demo scroll area

DemoScrollArea establishes native overflow and a keyboard focus stop. Its adopted fine border, compact radius and quiet surface make the scroll boundary visible against the diagonal canvas. The component caps its height at 16rem; set an explicit width or smaller height for the lesson. It does not add a child or change how content is laid out inside the scrollport.

<DemoScrollArea role="region" aria-label="Layer collection" className="h:10rem">  {/* Overflowing content */}</DemoScrollArea>

Give a named region when the collection needs a landmark, and keep the focus outline visible. The overflow reference uses real utility classes on its scrollports; the scroll area review compares the original Guide pattern, previous shared component and adopted boundary.

Demo viewport

DemoViewport hosts a complete site-authored document in a real iframe. The adopted treatment gives that viewport a fine edge and a quiet control deck, while preserving its actual width, height and content. A named preset, range slider or Fit changes the iframe width; theme, motion and print add only the controls needed by a lesson.

<DemoViewport  title="Responsive specimen"  document={html}  responsive  widthPresets={[{ label: 'Below sm', width: 833 }, { label: 'At sm', width: 835 }]}  height={180}/>

Derive breakpoint widths from the active preset; the numbers above illustrate the current sm boundary. A wide preset remains wide inside a narrow phone and scrolls within the stage. The padding reference responds to its iframe viewport, and the viewport review shows the original Guide control, previous shared chrome and adopted frame.

Demo motion

DemoMotion wraps an authored animation in a framed stage and places native Play/Pause and Replay buttons in a separate deck. It starts paused and uses the browser animation timeline: Pause preserves the current frame; Replay returns to the start before playing. The component also pauses when the operating system motion preference changes. Keep the movement, duration and easing in the specimen’s actual class or CSS.

<DemoMotion>  <div className="grid place-items:center h:10rem">    <DemoItem className="width:4rem height:4rem animation:rotate|2s|linear|infinite">↗</DemoItem>  </div></DemoMotion>

The stage adds no layout padding or dimensions, so set those in the example. The animation play-state reference uses its own real checkbox and CSS condition; the motion review compares the original Guide token scene with the previous and adopted shared playback treatment.

Document indexes

DocumentationIndex organizes a large catalog by section, category or letter. It powers the Guide and Reference entrances. Use complete descriptions for learning paths, and compact link lists for named API or utility lookups. Both views contain the same destinations.

Provide a stable id, title, description, icon and groups for each section. Groups with multiple categories receive native anchor shortcuts; give each group its own stable id so shared URLs survive reordering. showDescriptions enables complete, wrapping summaries. The default uses compact links. related supplies a cross-link to the other catalog.

<DocumentationIndex  name="guide"  sections={[{    id: 'learn', title: 'Learn',    description: 'Start with a working example.', Icon: IconBook,    groups: [{ entries: [{      id: 'intro', title: 'Introduction', category: 'Guide',      description: 'Write your first classes.',      url: '/guide/introduction',    }] }],  }]}  showDescriptions  related={{ href: '/reference', title: 'Reference',    description: 'Look up a utility.', Icon: IconBook }}/>

The catalog keeps the established card grid, with restrained icon boxes, clearer heading hierarchy and full mobile touch targets. It establishes its own container and column layout; place it in the reading column, outside measured demos. Category and A–Z controls are native buttons with pressed states. Letter and category shortcuts are real fragment links, including direct-entry URLs. Published catalogs omit idPrefix to retain their existing anchors; set distinct prefixes only when showing several catalogs on one review page. The complete category view is included in server-rendered HTML; A–Z switching requires JavaScript. The index review compares the original, previous and adopted treatments.

Document steps

Use DocumentSteps for a setup sequence with authored headings and code. Each DocumentStep gets a decorative two-digit number through DocumentStepNumber. Keep the action in the heading and its expected result in the prose. Reading order stays in the document.

@import "@master/css";

<DocumentSteps>  <DocumentStep columns>    <DocumentStepText>      <h3><DocumentStepNumber />Connect the stylesheet</h3>      <p>Import the entry in your app.</p>    </DocumentStepText>    <DocumentStepBody>{code}</DocumentStepBody>  </DocumentStep></DocumentSteps>

The components are server rendered. Supply native headings at the appropriate level and preserve their stable IDs. Numbering is decorative, not a replacement for headings or a progress indicator. The fine numbered rail inherits the original Guide’s sequence cue. The 36rem container threshold controls the optional two-column layout; narrower columns stack in reading order, and code retains its own horizontal scroll. Place measured demos outside the step layout. The steps review compares the original Guide, previous shared style and adopted treatment.

Use the same sequence pattern across installations:

• Quick start, Vite, CLI and VS Code pair each action with its result.
• Webpack, Rspack and Rsbuild keep full configuration files readable.
• Astro and SvelteKit connect layouts with server hooks.
• Express, PHP and Rails connect independently built assets with complete server templates.
• Laravel, WordPress and Shopify preserve the host's asset helpers and layout hooks.
• ASP.NET Core and Blazor make asset-build, host-build and publication order explicit.

Place a complete template before its appearance preview. DemoConfiguredExample uses literal source to keep displayed classes and rendered samples aligned; a preview does not run the host framework. Keep setup constraints in the lesson.

Installation mode navigation

InstallationModeTabs reuses the site’s navigation treatment for sibling setup guides. Pass translated labels and canonical destinations. One matching link receives aria-current="page". These are ordinary links with native keyboard behavior, not an in-page tab panel. The Blazor installation guide starts with static rendering; runtime rendering has its own route.

<InstallationModeTabs items={[  { href: '/guide/installation/blazor', label: 'Static Rendering' },  { href: '/guide/installation/blazor/runtime', label: 'Runtime Rendering' },]} />

Document values

Use DocumentValueList for reference facts that need a stable anchor and readable values. It keeps a compact key/value arrangement when the content column has room, then stacks each entry on narrow screens. Long values wrap without hiding content.

fast

--duration-fast

Default.15s

raised

--color-surface-raised

lightvar(--color-white)

darkvar(--color-gray-90)

smooth

--easing-smooth

Defaultcubic-bezier(.4, 0, .2, 1)

<DocumentValueList rows={[  { id: 'duration-fast', title: 'fast', identifier: '--duration-fast',    values: [{ label: 'Default', value: '.15s' }] }]} /><DocumentKeyList keys={['animation-duration:', 'transition-duration:']} />

Each row uses a real heading and an ordinary anchor link. IDs must be unique within the page; headingLevel={4} supports an entry nested below an existing third-level heading. Values remain selectable text. Use DemoTokenTable for token roles with visual specimens, and the existing code renderer for complete source examples. Both document components are static and live outside measured demo layouts.

Namespace consumers

Use DocumentNamespaceTable to map a namespace to its complete public consumers. Large rows show six keys initially; the native disclosure reveals the rest by mouse, touch, Enter or Space. All keys remain in the HTML and portable Markdown. This server component requires no client state and stays outside teaching geometry.

<DocumentNamespaceTable rows={[  { namespace: 'font-family', consumers: ['font:', 'font-family:'] }]} /><DocumentKeyList keys={consumerKeys} previewCount={6} />

DocumentKeyList shows every key by default. Set previewCount when a long lookup list would interrupt reading; keep essential instructions outside the disclosure. See the complete namespace registry.

Utility namespace table

NamespaceUtilityTable connects a token namespace to the utility keys that accept it. When groups have descriptions, the table keeps the original Guide's separate Group, Utility keys and Description columns. The refined shared style uses quiet separators and a consistent reading rhythm. On narrow screens the table scrolls inside its own keyboard-focusable region; the page width stays fixed.

<NamespaceUtilityTable groups={[  { label: 'Surfaces', namespace: 'color-surface',    keys: ['surface'], description: 'Panels, cards and overlays.' }]} />

Provide reader-facing group names and source keys from the manifest; namespace or namespaces filters unsupported keys. With no descriptions the table uses two columns. The table is a document aid, outside the measured layout of a demo. See its actual uses in Colors, Spacing and Typography, and the original/current/adopted review.

Numeric token table

ThemeNumberVariableTable reads numeric tokens and their units from the preset. The spacing representation uses the original Guide's pink diagonal field and raised objects to expose each actual gap. Its table has stable token and value columns, quiet row separators, and a keyboard-focusable scroll region on narrow screens.

<ThemeNumberVariableTable namespace="spacing" representation="spacing" />

The representation prop is optional. Breakpoints and Containers use the same data-driven table with descriptions, without the spacing specimen. Keep the native token value and reference unit visible in text, and place this inventory outside a measured layout demo. The numeric table review compares the original pink field with the previous neutral treatment and the adopted shared style.

File structure

Use DocumentFileTree for a static directory structure. Native nested lists preserve the hierarchy; monochrome icons are decorative. Entries can have a short description and nested children.

<DocumentFileTree title="Stylesheet package" entries={[  { name: 'package.json' },  { name: 'master.css', description: 'Public CSS source' },  { name: 'assets', children: [], description: 'Optional assets' }]} />

The optional caption belongs below the hierarchy. Keep descriptions short; they wrap below filenames in the reading column. Empty children marks an empty folder. This is a read-only list, so entries have no tab stops, expansion state or tree-widget keyboard behavior.

Use the same entry data when exporting a plain-text tree. See Monorepo and Authoring Packages for complete examples.

Discovery waterfall

DemoWaterfall shows illustrative request order with a text description and labeled resource rows. It has no time axis, FCP marker or animated playback. Keep measured results in the benchmark components.

<DemoWaterfall  title="A dependency discovered later"  description="The second request becomes known after the first resource loads."  rows={[    { label: 'Entry', start: 0, end: 40, tone: 'violet' },    { label: 'Dependency', start: 50, end: 90, tone: 'blue' }  ]}/>

Positions range from 0 to 100 and describe drawing geometry only. Use a description that explains the dependency in words; decorative bars are hidden from assistive technology. Rows stack their labels above the tracks in narrow containers. See critical resources. The waterfall review compares that Guide timeline, the earlier shared diagram and the adopted treatment.

Before and after CSS

DemoStyleComparison places identical, trusted HTML in two isolated browser documents. One uses native browser defaults; the other receives the supplied CSS. This makes the change in layout visible without flashing content or changing the surrounding page.

<DemoStyleComparison  html='<p class="message">Saved to your workspace.</p>'  css='.message { padding: 1rem; font: 500 1rem/1.5 system-ui; }'  height={160}/>

The previews use the same fixed height, with native scrolling when needed. The comparison grid owns layout outside each iframe; the unstyled document receives no demo reset or object styles. Pass site-authored markup only. See first-paint styling.

Document flow

DocumentFlow presents a short ordered process using real text and native list semantics. Numbered stages share the reading column on wide screens and stack when space is limited. It is a static explanation; the layout does not imply timings or an active step.

<DocumentFlow  title="Publish a document"  steps={[    { title: 'Write', description: 'Prepare the source content.' },    { title: 'Publish', description: 'Deliver the reviewed output.' }  ]}/>

Use two to four concise stages. An optional caption explains shared constraints below the stages. The component owns its grid, spacing and border; keep it outside any layout being measured. No controls, focus stops or animation are added.

DeliveryFlow supplies shared, exportable recipes for runtime and hydration, source scanning, native pruning and route styles. Their ordered text is included in search and Markdown.

Document choices

Use DocumentChoices for a small set of related destinations inside a reading column. Every link has a title, a short description and an optional decorative icon. Rows have generous click targets, a visible keyboard outline and native list semantics. Keep the whole row as one link; do not nest controls inside it.

<DocumentChoices label="Related guides" entries={[  { title: 'Theme Tokens', description: 'Shared product values.', href: '/guide/theme' }]} />

MigrationGuides adds the existing brand artwork and reads the same seven entries used by search and Markdown exports. See the migration overview. Use DocumentationIndex for large catalogs that need categories and alphabetical navigation. These navigation components sit outside teaching layouts.

Reading comparisons

Wrap a two-column Markdown table in DocumentComparison when readers need to compare prose or class syntax within the document column. Both columns stay visible on narrow screens; long syntax wraps. Use lists for decisions that need several paragraphs, and code blocks for source that must preserve its formatting. This static wrapper keeps native table headers and does not add demo geometry.

<DocumentComparison>| Existing CSS | Master CSS || --- | --- || `border-radius: .75rem` | `r:.75rem` |</DocumentComparison>

See migration utility mappings and rendering choices.

Syntax mappings

Use DocumentCodeTable for short syntax tokens paired with their native CSS. Row headers keep each token intact; CSS wraps at natural spaces. Keep long generated rules in code blocks. The table is a static reading aid, outside demo geometry.

<DocumentCodeTable label="Token" rows={[  { syntax: '@component', css: '@layer components' },  { syntax: '@reduce-motion', css: '@media (prefers-reduced-motion: reduce)' }]} />

The default first-column label is “Syntax”. The conditions reference uses this pattern for both named variants and arbitrary queries. Portable Markdown retains the original two-column table and every value.

Tool contracts

Use DocumentParameters for API inputs whose identifiers, types, and explanations need the full reading width. Required and optional states use text; neither is a validation control. Nested paths retain their full names and state when their parent is needed.

{  "type": "object",  "properties": { "className": { "type": "string", "minLength": 1 } },  "required": ["className"]}

<DocumentParameters label="Parameters" parameters={[  { name: 'className', type: 'string', requirement: 'Required', description: 'One complete class.' }]} /><DocumentDisclosure title="Complete input schema">  <Code lang="json">{schema}</Code></DocumentDisclosure>

Place both components in document flow, outside the layout being demonstrated. Use a plain sentence for an empty parameter list. Long code can scroll inside a disclosure; parameter descriptions wrap naturally. Keep the full contract in portable Markdown and search even when the page initially collapses it.

Used by class inspection, directive formatting, and CLI generation.

Tooling documentation

Use a readable option list for long identifiers, and a labeled source/result pair when explaining a tool. These static examples are checked against the actual lint and language-service output with the default preset.

bg-blue-60 p-md flex gap-sm

flex gap-sm p-md bg-blue-60

<span class="text-decoration:bad()">Note</span>

<button class="fg-white bg-blue-60:hover@sm">  Save</button>

@layer theme {  :root,  :host {    --color-blue-60: oklch(51.83% .2687 266.1)  }}@layer utilities {  @media (width>=52.125rem) {    .bg-blue-60\:hover\@sm:hover {      background-color: var(--color-blue-60)    }  }}

DocumentOptions keeps each identifier above its optional default and description. It uses native definition-list semantics; long names and values wrap without shrinking the prose into a narrow table cell. For prose authored directly in MDX, compose DocumentOptionList and DocumentOptionEntry; the paragraphs, links and inline code remain part of the portable document.

<DocumentOptionList label="Component interfaces">  <DocumentOptionEntry name="DemoSurface">    **Interface:** `elevation`, native div props.    A bordered surface with no implicit layout or padding. Elevation is opt-in.  </DocumentOptionEntry></DocumentOptionList>

Keep these document lists outside measured specimens. Each entry owns one term and its description; use ordinary paragraphs for separate interface details and layout constraints.

<DocumentOptions label="Feature settings" options={[  {    name: 'masterCSS.suggestSyntax',    defaultValue: 'true',    description: 'Offer contextual completion items.'  }]} />

DocumentCodeExample reuses the shared syntax highlighter. Source-only examples may show an error or warning; paired examples can use different source and result languages. Each block has a keyboard-accessible copy button and clipboard feedback. It remains readable when copying is unavailable.

<DocumentCodeExample  title="A stable class order"  language="mcss"  source="p-md flex"  result="flex p-md"  sourceLabel="Before sorting"  resultLabel="After sorting"/>

Use complete, verified strings. Code keeps its whitespace and may scroll inside its block; the option descriptions remain fluid. Neither component belongs inside a measured CSS lesson's flex or grid geometry. Keep the full text in the content export adapter.

See Code Linting for sorting, canonical forms, conflicts and diagnostic variants, and Language Service for completion, hover and formatter output.

Agent documentation

Prompts are prose that readers copy into another tool. DocumentPrompt preserves the exact text, wraps long lines, and keeps the copy action visible without presenting an editable field or a simulated chat.

Style this feature with Master CSS.

Reuse the project's tokens and component classes. Keep one-off layout decisions in markup. Add a shared token only for a repeated value or a named product decision.

Preserve HTML semantics, accessibility, and behavior. Run the available checks and inspect the result in the browser.

Set up the Master CSS MCP server for this project.

Project root: /absolute/path/to/project
Command: npx -y @master/css-mcp@rc --root /absolute/path/to/project

Identify the MCP client and use its native registration path. Do not assume every client reads mcp.json. Keep machine-specific absolute paths out of team configuration unless requested.

Verify the registration, reconnect the client if needed, then call mastercss_workspace_info. Confirm the returned root and manifest entries match this project.

<button class="bg-blue-60 p-md flex gap-sm">Save</button>

<button class="flex gap-sm p-md bg-blue-60">Save</button>

<DocumentPrompt  title="Review a component"  text="Review this component's classes and keyboard behavior."/>

Use a short title describing the task. Keep paragraphs and lists in the text itself so clipboard and portable exports preserve the full instructions. Short tasks and longer setup prompts use the same layout; both wrap within the reading column. The server renders the text and only the copy button needs client state.

Combine prompts with DocumentOptions for tool names, DocumentFlow for an ordered workflow, and DocumentCodeExample for verified before/after content. A workflow diagram does not execute a tool or imply that approval has been given. Keep prompts outside any measured demo geometry, and use ordinary code blocks when whitespace-sensitive source needs horizontal scrolling.

See AI Coding for context, review, and project-rule recipes, and MCP Server for the actual preview/apply process. The button specimen reuses the guide's configuration, HTML, and generated CSS.

Package APIs

DocumentAPIIndex keeps import paths and export names together with their purpose. It is a server-rendered navigation list: identifiers wrap at path separators and word boundaries without changing copied text, and each destination is a normal keyboard-accessible link. Use the compact variant for a list of symbols inside DocumentDisclosure.

export declare function createEngine(  options: MasterCSSEngineOptions): Promise<MasterCSSEngine>;

export interface MasterCSSCompileOptions {  readonly classes?: readonly string[];  readonly from?: string;  readonly preserveNativeCSS?: boolean;  readonly preserveNativeSource?: boolean;  readonly onDiagnostic?: (diagnostic: MasterCSSDiagnostic) => void;}

export interface MasterCSSInspectionReport {    readonly version: 4;    readonly cwd: string;    readonly inputs: Readonly<{        patterns: readonly string[];        files: readonly string[];        classes: readonly string[];    }>;    readonly scanner: Readonly<{        counts: Readonly<{            latent: number;            valid: number;            invalid: number;            native: number;            usedNative: number;            safelist: number;            blocklist: number;        }>;        classes: Readonly<{            latent: readonly string[];            valid: readonly string[];            invalid: readonly string[];            native: readonly string[];            usedNative: readonly string[];            safelist: readonly string[];            blocklist: readonly string[];        }>;        resetDependencies: readonly string[];    }>;    readonly stylesheets: Readonly<{        entries: readonly MasterCSSStylesheetInspection[];        dependencies: readonly string[];        warnings: readonly string[];        errors: readonly MasterCSSStylesheetError[];    }>;    readonly css: Readonly<{        bytes: number;        included: boolean;        text?: string;        emittedGlobals: Readonly<{            variables: number;            animations: number;        }>;    }>;    readonly missingCSS: Readonly<{        checked: readonly string[];        present: readonly MasterCSSMissingCSSResult[];        missing: readonly MasterCSSMissingCSSResult[];    }>;    readonly files: readonly MasterCSSSourceInspection[];    readonly inspections: readonly MasterCSSClassValidation[];    readonly diagnostics: readonly MasterCSSInspectionDiagnostic[];    readonly summary: Readonly<{        files: number;        stylesheets: number;        diagnostics: number;        errors: number;        warnings: number;        missingCSS: number;        invalidClasses: number;    }>;}

DocumentDeclaration reuses server syntax highlighting and the shared keyboard copy control. Declarations above 40 lines use a native disclosure; their full text stays in the document and portable exports. Long code lines scroll inside the code block. The component does not compile or execute TypeScript. Copy controls become available after client initialization; reading and native disclosures work before it.

<DocumentAPIIndex label="Import paths" entries={[  { name: '@master/css', href: '/reference/packages/css',    description: 'Engine sessions and class rendering.' }]} /><DocumentDeclaration label="Engine factory">{declaration}</DocumentDeclaration>

Keep these reading components outside demo geometry. Package pages derive declarations from TypeScript emission and retain public overloads, types, stable anchors and constructor restrictions. See Compiler, Runtime and Tooling for complete examples.

Stylesheet examples

Use StylesheetExample when a CSS directive changes the emitted stylesheet. The server compiles the literal source with the current preset and displays the complete result, including required variables and keyframes. The pair reuses DocumentCodeExample, including keyboard copy, visible focus and clipboard feedback. It does not execute a visual effect in the page.

@theme {  --color-brand: #4f46e5;}.card {  background-color: var(--color-brand);}

.card {  background-color: var(--color-brand);}@layer theme {  :root,  :host {    --color-brand: #4f46e5  }}

@theme inline {  --color-brand: #4f46e5;}@safelist "bg-brand";

@layer utilities {  .bg-brand {    background-color: #4f46e5  }}

@theme static {  --color-brand: #4f46e5;  @keyframes fade-in {    to { opacity: 1; }  }}

@layer theme {  :root,  :host {    --color-brand: #4f46e5  }}@keyframes fade-in {  to {    opacity: 1  }}

<StylesheetExample  title="An inline color token"  source={`@theme inline { --color-brand: #4f46e5; }@safelist "bg-brand";`}/>

The component accepts a title and standalone CSS source. Use a fixture-backed example for imports, references or assets that need multiple files. Keep the compiler on the server, retain every source and result line in portable Markdown, and allow code to scroll within its own block. A build error must surface during documentation checks.

The default, inline and static examples above share one presentation. DocumentOptions also accepts inline code and links in its description; its name and optional default stay separate. Both components belong outside measured demo layouts.

See Theme and variants, Managed definitions and Conditional blocks for working uses.

Benchmark charts

Use BenchmarkBars for values on a shared scale and BenchmarkStackedBars for composition within each row. The examples below use illustrative data, not measured results. See Benchmarks for real fixtures, sources, and limits.

BenchmarkChartGroup pairs a clearer metric heading with its unit and sample context, while leaving the established bars intact. The chart group review compares the original Guide chart, previous wrapper and adopted treatment. BenchmarkMetrics renders a refined definition list for short summaries, with tabular values and a detail line that stacks in narrow columns; its metrics review keeps the original Guide table visible. BenchmarkDataTable uses a refined native disclosure and a named, keyboard-focusable scroll region, so long tables retain complete rows and columns; its data table review preserves the Guide's original Expand control. BenchmarkSource marks a committed snapshot beside its recorded date; the source review compares it with the full Guide source table. BenchmarkFigure, BenchmarkDelta, and BenchmarkSampleSummary provide captions, contextual deltas, and sample statistics.

Keep series labels visible, include units and sample counts, and distinguish zero from missing data. Labels wrap; values use tabular numerals. A zero value has no colored fill. Stacked rows normalize to their own totals, so their lengths do not compare absolute payload size. Put important findings and limitations in the document body as well as the chart caption.

import { BenchmarkChartGroup, BenchmarkDataTable, BenchmarkSource } from '~/site/components/benchmarks'<BenchmarkChartGroup title="Style recalculation" detail="Median · 3 samples" unit="ms"  items={[{ id: 'fixture-a', label: 'Fixture A', value: 12.5, color: 'blue' }]} /><BenchmarkDataTable title="All recorded measurements">  <table>    <thead><tr><th scope="col">Fixture</th><th scope="col">Median</th></tr></thead>    <tbody><tr><th scope="row">Fixture A</th><td>12.5 ms</td></tr></tbody>  </table></BenchmarkDataTable><BenchmarkSource generatedAt="2026-07-01T00:00:00Z" href="/guide/benchmarks#data-sources" />

Charts and summaries render on the server and do not animate or change measurements. The table adds a small keyboard handler for consistent arrow-key scrolling, including mobile WebKit; disclosure remains native. Use nonnegative finite values with one unit per chart; use delta labels for signed changes. A max smaller than an item clips the visual scale and should be avoided. Tables may scroll horizontally inside their own region, never the document.

Code

Block code

<h1 class="block font-6xl tracking:.2em text-center">  Hello, world!</h1>

Inline code

• js -> const foo = 'bar'
• ts -> const options: Options = {}
• css -> body { background: red; }
• mcss -> text-center

Code lines added and removed

console.log('hewwo') console.log('hello') console.log('goodbye')

Code line highlight

console.log('hewwo')console.log('hello') console.log('goodbye')

Code line focus

console.log('hewwo')console.log('hello') console.log('goodbye')

Code mark words

const foo = 'bar'

Project style recipes

Use DemoConfiguredExample when a preview needs project tokens or managed classes. The same configuration and literal HTML supply the live iframe, visible code and complete generated CSS. Each preview owns its stylesheet and cannot change the surrounding document's theme, component classes or cascade.

<ProjectStyleExample name="tokens" /><ProjectStyleExample name="modes" /><ProjectStyleExample name="components" /><ProjectStyleExample name="layers" />

For a new lesson, supply its actual configuration and complete HTML:

<DemoConfiguredExample name="project-spacing" title="A project spacing token"  source="@theme { --spacing-card: 1.5rem; }"  html={'<article class="p-card">Collection details</article>'}  caption="p-card references --spacing-card." />

theme adds a real document-class switch; define explicit .light and .dark branches with @mode in the configuration when teaching that behavior. The default has no controls. code={false} is for a gallery specimen whose usage link leads to the complete source. These are server components; only the existing iframe controls hydrate. Use trusted site-authored HTML with literal classes. Content-sized previews suit ordinary document flow; use DemoViewport directly for bounded scrolling, fixed positioning or viewport geometry.

shadow places the HTML and generated utility rules inside a real open shadow root. Foundation variables inherit from the iframe document. This variant previews styling; it does not load a framework or test runtime lifecycle. Keep that distinction in the caption and document runtime setup in the linked lesson.

<button type="button" class="px-md py-sm r-sm bg-blue fg-white">Hello Lit</button>

@layer theme {  :root,  :host {    --spacing-md: 1rem;    --spacing-sm: .75rem;    --radius-sm: .25rem;    --color-blue: var(--color-blue-60);    --color-blue-60: oklch(51.83% .2687 266.1);    --color-blue-50: oklch(58.22% .2279 263.9)  }  @media (prefers-color-scheme:light) {    :root {      --color-blue: var(--color-blue-60)    }  }  @media (prefers-color-scheme:light) {    :host {      --color-blue: var(--color-blue-60)    }  }  @media (prefers-color-scheme:dark) {    :root {      --color-blue: var(--color-blue-50)    }  }  @media (prefers-color-scheme:dark) {    :host {      --color-blue: var(--color-blue-50)    }  }}@layer utilities {  .r-sm {    border-radius: var(--radius-sm)  }  .py-sm {    padding-block: var(--spacing-sm)  }  .px-md {    padding-inline: var(--spacing-md)  }  .bg-blue {    background-color: var(--color-blue)  }  .fg-white {    color: oklch(100% 0 none)  }}

<DemoConfiguredExample name="shadow-button" title="Shadow-root styling"  source="" html={'<button class="px-md py-sm bg-blue fg-white">Hello</button>'}  caption="Generated CSS inside a shadow root." shadow />

Used by Lit installation. The same default preview also supports the rendered markup in React and Vue.

For formal rules that need code without a live preview, ConfiguredExample accepts the same source and literal html (or its existing classes shorthand). It uses the same native-property support as the preview and includes complete generated CSS.

Platform behavior

Use DemoFeatureSupport beside a native CSS example to report the current browser's syntax support. It never changes the specimen's styles. Keep a usable fallback in the example; a positive result is not a visual conformance guarantee. The support label review compares the Guide's original guidance with the previous and adopted live labels.

(field-sizing: content)Checking this browser…

selector(:has(:checked))Checking this browser…

<DemoFeatureSupport condition="(field-sizing: content)" /><ProjectStyleExample name="nativeField" />

The field and checkbox recipes above are used in Compatibility. The status starts with a neutral checking label during server rendering, then reports the browser's actual CSS.supports() result. Supported and unsupported states retain the same layout and textual explanation.

DemoViewTransition provides two isolated interactive examples. The default is view selection; the article variant demonstrates matching snapshot names and focus restoration. Both use the existing iframe component and shared controls.

<DemoViewTransition /><DemoViewTransition example="articles" />

Each preview owns a document and a bounded scroll area. It cannot capture the documentation page's root snapshot. The scene uses unique element names, skips animations for reduced motion and retains an immediate update when the API is unavailable. These are scenario recipes, not application navigation components. See View Transitions for framework-neutral markup, generated CSS and platform constraints.

Typography and motion recipes

Use FoundationTypography for a complete reading hierarchy and FoundationTypeComparison to compare raw size with a full text treatment. Both keep all content visible and preserve the same font resources. Computed size, leading and tracking are reported outside the measured text.

<FoundationTypography /><FoundationTypeComparison /><FoundationMotion /><FoundationTransition /><FoundationDialog />

FoundationMotion starts paused and retains finite native timelines for replay. Its authored media conditions still apply: reduced motion shows the final content without an animation. FoundationTransition uses a native checkbox with explicit endpoints and removes both duration and delay under reduced motion. FoundationDialog opens a real modal inside a bounded iframe; its entrance runs once, and closing remains immediate. Keep focus, names and descriptions in the HTML.

Color and elevation recipes

DemoThemeComparison renders the same trusted HTML in two independent preview documents. Both use real mode variables. Content sizing keeps normal-flow content visible; use DemoViewport directly for viewport-dependent or scroll-boundary lessons.

<DemoThemeComparison  name="surface-card"  title="A shared surface"  html='<article class="p-md surface-raised text-body">Notes</article>'/>

DemoPalette reads fixed preset colors and copies CSS variable references. Pass families={['blue', 'violet']} for a focused set. DemoCopyButton accepts value, label, an optional icon, native button attributes and children. Text controls use a copy icon by default; color chips pass icon={null}. Its status confirms successful writes or explains when the browser declines clipboard access.

The palette review compares the original Guide palette, the earlier shared gallery and the adopted token gallery. The Guide's existing copyable palette remains in place.

<DemoCopyButton value="var(--color-blue-60)" label="Copy blue token">  Copy token</DemoCopyButton>

The copy control review compares the Guide swatch, earlier button and adopted treatment.

DemoTokenTable groups each token with its utilities, leaving a readable column for its role or value. Rows may include a decorative preview. Keep inventory tables outside the measured scene and derive their values from preset data.

<DemoTokenTable rows={[  { token: '--shadow-sm', utilities: ['shadow-sm'],    description: 'A small raised surface.' }]} />

The palette does not choose foreground/background pairs. In color tables, direct variable previews are inventories; practical recipes use complete literal utilities. Shadow examples supply enough canvas space for paint and preserve the focus outline.

Foundation recipes

Use practical compositions when teaching layout decisions. These shared specimens appear in the Guide; their links identify the owning lesson. Native links and checkboxes remain usable inside page previews.

<FoundationBreakpoint /><FoundationContainerGrid /><FoundationMedia /><FoundationSizing /><FoundationAxes /><FoundationShrink /><FoundationRadius /><FoundationShapes />