\n Add your first item to get started. It will appear here when you do.\n
\n
\n \n
\n",
"description": "A clear starting point when there is no content to show.",
"contract": "Use a contextual heading, brief guidance, and optional native actions. Match the heading level to the page. Empty states are static, not alerts or loading indicators. Wire actions to your application; no runtime is included. Keep important guidance visible and reuse shared buttons and theme tokens.",
"usage": [
{
"title": "Add an optional icon",
"text": "Place an SVG with class icon before the heading. Use aria-hidden=true and focusable=false when the heading already communicates its meaning. Omit it for a simpler presentation."
},
{
"title": "Give a clear next step",
"text": "Use a short heading, a helpful explanation, and one or two relevant actions. Keep actions functional in your application."
},
{
"title": "Keep it accessible",
"text": "Choose the appropriate heading level and label the section with aria-labelledby. Avoid live announcements on initial load; announce updates separately when needed."
}
],
"javascriptBytes": 0,
"url": "/components/empty-state"
},
{
"id": "button",
"name": "Buttons",
"kind": "components",
"dependencies": [
"button"
],
"html": "
\n Use real links for navigation and buttons for actions.\n
",
"description": "Primary and secondary actions.",
"contract": "Use a native button with type=button for actions or type=submit for form submission; use an anchor with a real href for navigation. btn is primary; secondary and ghost are quieter alternatives. btn-large, btn-icon, and btn-pill adjust size or shape. btn-gradient opts primary buttons into the theme\u2019s multicolor fill and hover paint; secondary and ghost remain quiet. btn-choice stacks a sample and label with balanced padding and an inset keyboard focus outline. Keep 44px minimum targets. Label icon-only buttons with aria-label and hide decorative SVGs. Use native disabled on buttons, never on anchors. aria-disabled alone does not prevent activation. Busy examples use disabled plus aria-busy and visible text; implement your own request, error handling, duplicate-submission guard, and completion announcement outside the busy control. All demo actions are illustrative. Shared 300ms color and hover-highlight transitions respect reduced motion and data-motion=none; focus remains immediate. No lift, scale, automatic loading animation, or runtime JavaScript is required.",
"usage": [
{
"title": "Choose the right element",
"text": "Use `button` for actions and an anchor with a real `href` for navigation. Set the button\u2019s `type` explicitly."
},
{
"title": "Choose an emphasis",
"text": "Start with `.btn`. Add `.secondary` or `.ghost` for quieter actions; use `.btn-large`, `.btn-icon`, or `.btn-pill` when needed."
},
{
"title": "Handle states clearly",
"text": "Label icon-only buttons. Use `disabled` for unavailable buttons, and visible progress text with `aria-busy` while working. Your app handles requests and errors."
}
],
"javascriptBytes": 0,
"url": "/components/button"
},
{
"id": "link",
"name": "Links",
"kind": "components",
"dependencies": [
"link"
],
"html": "\n Explore the Docs\n",
"description": "Recognizable navigation with native browser behavior.",
"contract": "Use a native anchor with a meaningful href and descriptive visible text. link-underline keeps a persistent background underline for standalone links, sharing position and thickness with link-animated; hover and press use shared color transitions, with immediate keyboard focus. Base CSS handles reduced motion and data-motion=none. Add link-animated to opt into a 300ms underline reveal on hover with immediate keyboard focus for short standalone links. Native underlines remain the default for prose and long labels; omit link-underline for those. RTL reverses the reveal direction; motion opt-outs make it immediate. Keep prose links underlined and sentence-cased in context; standalone navigation uses title case. Use a button for actions, never href=# or javascript: as a substitute. Do not add role=button, redundant tabindex, or disabled to an anchor. For unavailable destinations render plain explanatory text instead of a fake disabled link. Prefer the same tab; if a new tab is needed, disclose it in visible text and use target=_blank with rel=noopener. Set aria-current=page only for the current navigation destination. Keep real hrefs for crawling, browser menus, and modifier-click; no click interception or runtime is required. Use spacious cluster or navigation layouts for standalone targets; inline prose links follow text flow. Do not truncate meaningful link labels. Downloads must identify their content and use a real file URL; download is a browser hint, not a guarantee. Do not claim ranking improvements from this component.",
"usage": [
{
"title": "Make destinations clear",
"text": "Use a real `href` and descriptive text. Keep regular text links underlined. Actions belong on buttons."
},
{
"title": "Choose an underline",
"text": "Use `.link-underline` for short standalone links. Add `.link-animated` for the optional reveal. Leave these classes off long links in prose."
},
{
"title": "Preserve browser behavior",
"text": "Keep native navigation, keyboard focus, and modifier-click. If a link opens a new tab, say so and add `rel=\"noopener\"`."
}
],
"javascriptBytes": 0,
"url": "/components/link"
},
{
"id": "badge",
"name": "Badges",
"kind": "components",
"dependencies": [
"badge"
],
"html": "
\n \n Published\n \n \n Draft\n \n
",
"description": "Readable status labels.",
"contract": "Use badge on a span for a short, noninteractive label. Add one emphasis class: badge-neutral, badge-outline, or badge-solid. Pills are the default; add badge-rounded for rounded rectangles or badge-count for numbers. badge-pill remains a compatibility alias. Icons inherit color and size; hide decorative SVGs from assistive technology. Keep visible text and context, never color alone. Do not add tabindex or button roles to static badges. Use a real link or button for actions, with a suitable hit area. For meaningful dynamic updates, put role=status on a containing message and update its text; avoid announcing every counter change. Static badges never animate or enter the tab order. Do not use a badge for an action or a dismissible chip. Customize the shared palette tokens for both themes and verify text contrast of at least 4.5:1 on the actual surface. Avoid truncating essential status text. Dismissible chips, notification overlays, and automatic count formatting are not implemented.",
"usage": [
{
"title": "Label a status",
"text": "Use `.badge` on a `span` for short text such as Published or Draft. Include words or context so color is never the only clue."
},
{
"title": "Adjust the appearance",
"text": "Choose `.badge-neutral`, `.badge-outline`, or `.badge-solid`. Pills are the default; use `.badge-rounded` for a rectangular shape."
},
{
"title": "Keep it informational",
"text": "Badges are not buttons or dismissible chips. Use `.badge-count` for numbers and announce only meaningful status changes."
}
],
"javascriptBytes": 0,
"url": "/components/badge"
},
{
"id": "card",
"name": "Cards",
"kind": "components",
"dependencies": [
"panel"
],
"html": "\n
\n Your workspace\n
\n
\n A place for your next idea.\n
\n
\n A flexible surface for content, actions, or a project summary.\n
\n",
"description": "A themed surface with consistent spacing.",
"contract": "Compose panel and stack with native header, content, and footer. --space controls padding and stack gaps (24px default, 16px compact). Use article only for standalone content; otherwise use a div or an appropriately named section. Choose heading levels from page context. Cards are static containers, not buttons: no tabindex, click handler, or hover lift. Use real anchors for navigation and native buttons for actions; never nest interactive controls in a wrapping link. Do not clip keyboard focus or impose fixed heights. Supply image width and height to reserve space, meaningful alt text for informative images, and empty alt for decoration; lazy-load only below-the-fold media. Use responsive local images; card CSS does not fetch media. Keep descriptions readable and verify contrast after customizing tokens. No runtime, entrance motion, data fetching, or persistence is included.",
"usage": [
{
"title": "Compose the content",
"text": "Combine `.panel` and `.stack`. Add a heading, body, and optional footer. Use `article` only when the content stands on its own."
},
{
"title": "Keep spacing consistent",
"text": "`--space` controls padding and gaps: 24px by default, or 16px for a compact card. Let content determine the height."
},
{
"title": "Add actions and images",
"text": "Use real links or buttons inside the card. Give images dimensions and appropriate alt text. Static cards do not need hover motion or keyboard focus."
}
],
"javascriptBytes": 0,
"url": "/components/card"
},
{
"id": "field",
"name": "Input",
"kind": "components",
"dependencies": [
"field"
],
"html": "
\n \n \n
\n Choose a name your team will recognize.\n
\n
",
"description": "Native text entry with clear labels and useful states.",
"contract": "Use a native input with class=input and a visible associated label. Compose label, control, and help in field. Use unique ids, name for submitted values, aria-describedby for help/errors, and appropriate type, autocomplete and inputmode. Placeholder is an example, never a label. Mark required visibly and with required. Set aria-invalid=true only after validation, describe how to fix the error, and clear the state when corrected. aria-invalid does not enforce validity; validate on the server too. Disabled controls cannot be edited, focused, or submitted; readonly values remain focusable and submitted. Do not block paste or password managers. Default targets are at least 44px with 16px input text; input-large is 52px. Shared color transitions respect reduced motion and data-motion=none; focus is immediate. No automatic animation, masking, floating labels, requests, storage, or runtime JavaScript is included. Keep instructions in semantic HTML; input styling does not improve search ranking. The field kit id and field.css filename remain stable for existing kits.",
"usage": [
{
"title": "Start with a label",
"text": "Group a visible label, `input.input`, and help text in `.field`. Connect the label with `for` and a unique input `id`."
},
{
"title": "Help people enter data",
"text": "Choose the right `type`, `autocomplete`, and `inputmode`. Keep placeholders as examples and allow paste and password managers."
},
{
"title": "Explain errors",
"text": "Link help and errors with `aria-describedby`. Set `aria-invalid=\"true\"` after validation and explain the fix. Your server still needs to validate submissions."
}
],
"javascriptBytes": 0,
"url": "/components/input"
},
{
"id": "accordion",
"name": "Accordion",
"kind": "components",
"dependencies": [
"disclosure",
"accordion"
],
"html": "
\n \n \n What do I need to get started?\n \n
\n Plain HTML and CSS. No packages or build step required.\n
\n \n \n \n Can I customize the design?\n \n
\n Use shared tokens for colors, spacing, and motion.\n
\n \n \n \n Does it work without JavaScript?\n \n
\n Yes. The browser manages expansion and keyboard interaction.\n
\n \n
",
"description": "Related sections with native expansion and consistent spacing.",
"contract": "Compose an accordion wrapper with native details and summary. Include base, disclosure, and accordion CSS once. Use a unique shared name per single-open group; omit name for multiple-open groups. Use open for initial state, with at most one initially open item per named group. Older browsers without name support allow multiple open items. Tab and Shift+Tab navigate; Enter and Space toggle. Arrow, Home, and End navigation are not implemented. Native semantics expose expansion; do not add redundant roles, tabindex, or aria-expanded. Keep summary first, descriptive, and free of nested controls. Use disclosure-content stack for rich bodies. Use an external context-appropriate heading to introduce the group. accordion-bordered adds a themed outline and inset spacing. accordion-plus replaces the chevron with a decorative plus that rotates 45 degrees into a cross. Native details has no disabled state: show unavailable information as visible text instead of faking disabled controls. Keep essential instructions visible, content in source HTML, and links inside bodies. No runtime, requests, persistence, or SEO ranking guarantee. Shared 300ms chevron and progressive height motion honor reduced motion and data-motion=none; unsupported browsers expand immediately. Check focus, collapsed links, rapid toggles, long text, narrow screens, RTL, and all palettes. Use the native open property and toggle event for application-owned behavior.",
"usage": [
{
"title": "Start with a group",
"text": "Wrap `details` in `.accordion`. Put each question in `summary` and its answer below."
},
{
"title": "Choose what stays open",
"text": "Share a unique `name` for one open item at a time. Omit it to allow several. Add `open` to start expanded."
},
{
"title": "Make it yours",
"text": "Use `.accordion-bordered` for an outline or `.accordion-plus` for a rotating plus."
},
{
"title": "Keyboard and motion",
"text": "Tab moves focus; Enter or Space toggles. Motion respects reduced motion. `data-motion=\"none\"` disables it locally."
},
{
"title": "Keep answers usable",
"text": "Put links in answers. Keep essential instructions outside the accordion."
},
{
"title": "Know the limits",
"text": "No JavaScript needed. Older browsers may allow multiple open answers. No arrow-key navigation or disabled items."
}
],
"javascriptBytes": 0,
"url": "/components/accordion"
},
{
"id": "disclosure",
"name": "Disclosure",
"kind": "components",
"dependencies": [
"disclosure"
],
"html": "\n \n Can I use only this component?\n \n
\n Yes. Include the shared base and this component\u2019s CSS. No JavaScript is needed.\n
\n",
"description": "Expandable content using native details.",
"contract": "Put a descriptive summary first in details. Use Enter or Space to toggle and Tab to move between controls. Keep links and buttons out of the summary. Native semantics expose state; do not add redundant role, tabindex, or aria-expanded. Use open for initial state, the open property and toggle event for optional application logic, and a unique shared name for an exclusive group. Omit name for independent items. This is not an arrow-key accordion. Use disclosure-content stack for rich bodies. Keep essential instructions visible and content in the HTML; collapsed content is not a security boundary or an SEO guarantee. The label prevents accidental selection; body text stays selectable. Motion uses shared tokens, respects reduced motion and data-motion=none, and animates height where supported. Other browsers retain instant native expansion.",
"usage": [
{
"title": "Reveal extra detail",
"text": "Use native `details` with a descriptive `summary` first. Add `open` when the content should start visible."
},
{
"title": "Add richer content",
"text": "Use `.disclosure-content.stack` for paragraphs and links. Keep interactive controls out of the summary."
},
{
"title": "Use native behavior",
"text": "Tab moves focus; Enter or Space toggles. No JavaScript is needed. Motion respects user preferences, with immediate expansion in unsupported browsers."
}
],
"javascriptBytes": 0,
"url": "/components/disclosure"
},
{
"id": "table",
"name": "Tables",
"kind": "components",
"dependencies": [
"table"
],
"html": "
\n
\n
\n Example projects\n
\n \n
\n
\n Project\n
\n
\n Status\n
\n
\n Members\n
\n
\n \n \n
\n
\n Website\n
\n
\n Published\n
\n
\n 8\n
\n
\n
\n
\n Customer portal\n
\n
\n In progress\n
\n
\n 4\n
\n
\n
\n
\n Documentation\n
\n
\n Draft\n
\n
\n 2\n
\n
\n \n
\n
",
"description": "A responsive semantic data table.",
"contract": "Use native table, caption, thead, tbody, and scoped column/row headers. Keep row labels readable and numbers aligned with table-number; format currency and dates in the application. Wrap wide tables in table-scroll with tabindex=0, role=region, and an accessible name tied to the caption; provide a visible scrolling hint when needed. Inside table-scroll, --table-min sets a readable minimum width (28rem default); use 100% for short tables that should fit. Text wraps while table-number preserves numeric values. Preserve column relationships on small screens instead of hiding important columns or converting cells to cards. Table-striped and table-compact are optional; retain usable targets when cells contain controls. Use descriptive links or buttons inside cells, never clickable or focusable rows. Use colspan matching the column count for empty-state messages. Keep source data in HTML for no-JavaScript access and crawlers; escape untrusted text or use textContent. This static table has no sorting, selection, filtering, pagination, virtualization, or fetching. Implement those separately only when needed; sorting requires native buttons, accurate aria-sort, and announcements of changes. Do not use role=grid unless implementing its complete keyboard model. Static rows have no entrance motion or misleading hover affordance; interactive children use shared motion and focus standards. Validate keyboard scrolling, zoom/reflow, RTL, theme contrast, and screen-reader header associations.",
"usage": [
{
"title": "Describe the data",
"text": "Use a `caption` and scoped row and column headers. Apply `.table-number` to numbers that should align for comparison."
},
{
"title": "Make room on small screens",
"text": "Wrap wide tables in `.table-scroll` with a name and `tabindex=\"0\"`. Keep important columns visible and let the region scroll."
},
{
"title": "Add only what you need",
"text": "Use `.table-striped` or `.table-compact` for presentation. Sorting, filtering, pagination, and fetching are application features, not built into this table."
}
],
"javascriptBytes": 0,
"url": "/components/table"
},
{
"id": "bar-chart",
"name": "Progress",
"kind": "components",
"dependencies": [
"chart"
],
"html": "\n \n Example weekly signups\n \n
\n
\n
\n Mon\n
\n
\n \n 42 of 100\n \n
\n
\n 42\n
\n
\n
\n
\n Tue\n
\n
\n \n 68 of 100\n \n
\n
\n 68\n
\n
\n
\n
\n Wed\n
\n
\n \n 55 of 100\n \n
\n
\n 55\n
\n
\n
\n
\n Thu\n
\n
\n \n 91 of 100\n \n
\n
\n 91\n
\n
\n
\n",
"description": "Compact, labeled bars with native meters.",
"contract": "For small nonnegative datasets. Give all meters the same maximum, visible labels and values, and accessible names. Not a general-purpose plotting engine.",
"usage": [
{
"title": "Choose a fill",
"text": "Bars use the theme accent by default. Set --bar-color on the chart or a row for another color. Keep visible labels and values; color must not carry meaning alone."
},
{
"title": "Show a small comparison",
"text": "Use these bars for a small set of nonnegative values. Give every meter the same maximum."
},
{
"title": "Keep values readable",
"text": "Show a label and number for each bar, with an accessible name. This is a compact summary, not a full charting engine."
}
],
"javascriptBytes": 0,
"url": "/components/bar-chart"
},
{
"id": "hero",
"name": "Hero",
"kind": "blocks",
"dependencies": [
"button",
"panel"
],
"html": "\n
\n Design with AI. Build like a pro.\n
\n
\n Your next idea.\n \n Ready for the web.\n
\n
\n Thoughtful components, balanced spacing, and a shared design language for you and your AI.\n
\n Replace this example with your product\u2019s story.\n
\n",
"description": "An introduction with a clear next step.",
"contract": "Use a single page h1 when this is the main hero. Replace the sample destination with a real section or page.",
"usage": [
{
"title": "Introduce the page",
"text": "Replace the example copy with a clear promise and next step. Use the page\u2019s `h1` when this is its main introduction."
},
{
"title": "Connect the action",
"text": "Give the call to action a real destination. Keep the heading and supporting copy brief enough to scan."
}
],
"javascriptBytes": 0,
"url": "/blocks/hero"
},
{
"id": "features",
"name": "Feature grid",
"kind": "blocks",
"dependencies": [
"panel"
],
"html": "\n
\n Built around your work.\n
\n
\n \n
\n Familiar code\n
\n
\n Semantic HTML and ordinary CSS you can edit.\n
\n \n \n
\n Only what you need\n
\n
\n Select the pieces that belong in your project.\n
\n \n \n
\n Your design\n
\n
\n Shared tokens keep details consistent.\n
\n \n
\n",
"description": "Three benefits in a responsive grid.",
"contract": "Use descriptive headings. Grid collapses without JavaScript; cards share the foundation tokens.",
"usage": [
{
"title": "Lead with benefits",
"text": "Replace each sample with a useful benefit and a descriptive heading. Keep related descriptions similar in length."
},
{
"title": "Let the grid adapt",
"text": "The grid rearranges without JavaScript. Use shared spacing and color tokens to keep the cards consistent."
}
],
"javascriptBytes": 0,
"url": "/blocks/features"
},
{
"id": "stats",
"name": "Stat cards",
"kind": "blocks",
"dependencies": [
"panel"
],
"html": "\n
\n Workspace overview\n
\n
\n Illustrative data, not connected to a service.\n
\n
\n \n
\n Projects\n
\n
\n 14\n
\n \n \n
\n Members\n
\n
\n 28\n
\n \n \n
\n Published\n
\n
\n 8\n
\n \n
\n",
"description": "A row of clearly labeled metrics.",
"contract": "Label units and time ranges for real data. Do not imply demo values are live. No LayoutDB API exists yet.",
"usage": [
{
"title": "Give numbers context",
"text": "Label each metric and include its units and time range. Make clear whether a value is live or illustrative."
},
{
"title": "Connect your own data",
"text": "The examples use static values. Your application supplies updates; no database connection is included."
}
],
"javascriptBytes": 0,
"url": "/blocks/stats"
},
{
"id": "landing",
"name": "Marketing starter",
"kind": "templates",
"dependencies": [
"hero",
"features",
"disclosure"
],
"html": "\n
\n Design with AI. Build like a pro.\n
\n
\n Your next idea.\n \n Ready for the web.\n
\n
\n Thoughtful components, balanced spacing, and a shared design language for you and your AI.\n
\n Replace this example with your product\u2019s story.\n
\n\n\n
\n Built around your work.\n
\n
\n \n
\n Familiar code\n
\n
\n Semantic HTML and ordinary CSS you can edit.\n
\n \n \n
\n Only what you need\n
\n
\n Select the pieces that belong in your project.\n
\n \n \n
\n Your design\n
\n
\n Shared tokens keep details consistent.\n
\n \n
\n\n\n
\n Frequently asked questions\n
\n \n \n Can I use only this component?\n \n
\n Yes. Include the shared base and this component\u2019s CSS. No JavaScript is needed.\n
\n \n",
"description": "A composed hero, benefits, and FAQ.",
"contract": "Replace sample content and destinations. Includes only its declared component styles. No form processing, analytics, or backend.",
"usage": [
{
"title": "Tell your story",
"text": "Replace the sample hero, benefits, and questions with your product\u2019s content. Check heading order and action destinations."
},
{
"title": "Build on the foundation",
"text": "The starter includes only its declared component styles. Add your own forms, analytics, or backend when needed."
}
],
"javascriptBytes": 0,
"url": "/templates/landing",
"sections": [
"
Design with AI. Build like a pro.
Your next idea. Ready for the web.
Thoughtful components, balanced spacing, and a shared design language for you and your AI.
\n Illustrative data, not connected to a service.\n
\n
\n \n
\n Projects\n
\n
\n 14\n
\n \n \n
\n Members\n
\n
\n 28\n
\n \n \n
\n Published\n
\n
\n 8\n
\n \n
\n\n\n
\n Recent projects\n
\n
\n
\n
\n Example projects\n
\n \n
\n
\n Project\n
\n
\n Status\n
\n
\n Members\n
\n
\n \n \n
\n
\n Website\n
\n
\n Published\n
\n
\n 8\n
\n
\n
\n
\n Customer portal\n
\n
\n In progress\n
\n
\n 4\n
\n
\n
\n
\n Documentation\n
\n
\n Draft\n
\n
\n 2\n
\n
\n \n
\n
\n\n\n
\n Audience activity\n
\n \n \n Example weekly signups\n \n
\n
\n
\n Mon\n
\n
\n \n 42 of 100\n \n
\n
\n 42\n
\n
\n
\n
\n Tue\n
\n
\n \n 68 of 100\n \n
\n
\n 68\n
\n
\n
\n
\n Wed\n
\n
\n \n 55 of 100\n \n
\n
\n 55\n
\n
\n
\n
\n Thu\n
\n
\n \n 91 of 100\n \n
\n
\n 91\n
\n
\n
\n \n",
"description": "A data overview assembled from shared pieces.",
"contract": "Static example data. Integrate your own data source with safe text rendering; authentication, APIs and LayoutDB integration are not implemented.",
"usage": [
{
"title": "Start with the overview",
"text": "Replace the sample metrics, projects, and chart values. Give real data clear labels, units, and time ranges."
},
{
"title": "Connect responsibly",
"text": "Your application owns authentication and data fetching. Render untrusted values safely as text; the starter has no backend connection."
}
],
"javascriptBytes": 0,
"url": "/templates/dashboard",
"sections": [
"
\n \n Top\n \n \n A little context, right where you need it.\n \n \n Right\n \n \n A little context, right where you need it.\n \n \n Bottom\n \n \n A little context, right where you need it.\n \n \n Left\n \n \n A little context, right where you need it.\n \n
",
"description": "Small, contextual hints on hover, focus, or touch.",
"contract": "Include tooltip.css and tooltip.js once. Link a focusable trigger to a unique role=tooltip ID with aria-describedby; add data-tooltip=top, right, bottom, or left. Position flips and clamps at viewport edges. Escape dismisses; focus stays on the trigger. Keep essential help visible and tooltip content short, plain text, and noninteractive. Do not use on disabled controls or as a replacement for an accessible label. Without JavaScript the supplemental hint stays hidden. Use textContent for dynamic text. Preserve the trigger\u2019s accessible name; aria-describedby may include other help IDs. Avoid title attributes, live regions, and focus transfer. Hints remain hoverable; Escape dismissal persists until leaving the trigger or a new touch. Touch preserves the trigger action. Placement directions are physical, including in RTL. Tooltips fade and slide 4px from the resolved side by default, using shared 300ms timing. The 120ms pointer-leave grace period allows travel into the hint. Reduced motion disables animation; data-motion=none on a common ancestor opts out locally. No packages required.",
"usage": [
{
"title": "Add a little context",
"text": "Connect the trigger to a unique tooltip ID with `aria-describedby`. Put `data-tooltip=\"top\"` on the trigger to choose a preferred side."
},
{
"title": "Keep help accessible",
"text": "Tooltips open on hover, focus, or touch; Escape dismisses them. Keep essential instructions visible and avoid links or buttons inside the hint."
},
{
"title": "Choose the motion",
"text": "Tooltips keep a simple theme-aware surface and arrow across styles, and fade and slide 4px. Both effects respect reduced motion. Include the tooltip script once."
}
],
"javascriptBytes": 3858,
"url": "/components/tooltip"
},
{
"id": "dialog",
"name": "Dialog",
"kind": "components",
"dependencies": [
"button",
"field",
"dialog"
],
"html": "
\n Try Escape, Tab, and Shift+Tab. Closing returns focus to the button. These examples do not save or delete data. JavaScript is required to open them.\n
\n\n \n
\n A little room to focus.\n
\n \n
\n
\n Keep a focused task in view while the rest of the page takes a step back.\n
\n
\n This example also closes when you click the backdrop.\n
\n
\n \n\n\n \n
\n Discard this draft?\n
\n \n
\n
\n This is a confirmation preview. No draft will be discarded. In your app, explain the consequence before asking someone to continue.\n
\n
\n \n\n\n \n
\n Make yourself at home.\n
\n \n \n\n\n \n
\n Space for the whole story.\n
\n \n
\n
\n The body scrolls while the heading and actions stay visible.\n
\n
\n One task at a time\n
\n
\n Keep the purpose clear. Use a page for a separate destination.\n
\n
\n A clear next step\n
\n
\n Choose specific labels. Give people a way to cancel.\n
\n
\n Every screen\n
\n
\n Try a narrow window or larger text. Actions stay within reach.\n
\n
\n Keyboard access\n
\n
\n Use Tab to move, Escape to close, and return to your starting point.\n
\n
\n \n",
"description": "Focused overlays for information, decisions, and forms.",
"contract": "Use native dialog with class=dialog and aria-labelledby pointing to its heading. Open with a button carrying data-dialog-open=ID and aria-controls=ID; close with data-dialog-close or a form method=dialog. Include dialog.css and dialog.js once. Use autofocus deliberately; confirmations should focus the safe action. Escape cancels and native modal focus returns to the opener. Add data-dialog-dismiss only for optional backdrop dismissal. dialog-wide changes width; --dialog-width customizes it. Listen to the native close event and returnValue for choices. Real submissions need your own validation, persistence and error handling; do not treat closing as a successful save. Keep a visible cancel or close control. JavaScript is required to open these examples. Keep essential information available on the page without opening a modal. Escape, backdrop dismissal, and close controls produce cancel; method=dialog buttons return their explicit value. Opening resets returnValue and body scroll. Form and confirmation examples do not dismiss on backdrop clicks. Native disabled and aria-disabled openers are ignored. Verify Tab and Shift+Tab containment, focus return, validation, short viewports, RTL, reduced motion, and repeated opening. Initial focus should favor the safe action or a reading heading; do not autofocus a destructive action. Dialogs are for focused tasks, not indexable standalone destinations.",
"usage": [
{
"title": "Open a focused task",
"text": "Use `dialog.dialog` with a visible title linked by `aria-labelledby`. Connect an opener with `data-dialog-open` and the dialog\u2019s ID."
},
{
"title": "Offer a clear way out",
"text": "Include a close or cancel button. Escape closes the dialog and focus returns to the opener. Use `autofocus` deliberately, favoring the safe action."
},
{
"title": "Own the result",
"text": "Include the dialog script once. Your app handles validation, saving, and errors. Closing a dialog does not mean data was saved."
}
],
"javascriptBytes": 2172,
"url": "/components/dialog"
},
{
"id": "tabs",
"name": "Tabs",
"kind": "components",
"dependencies": [
"tabs",
"select",
"section-nav"
],
"html": "
\n Keep the work, people, and next steps in one place.\n
\n \n \n
\n Recent activity\n
\n
\n Your team has published the first design review.\n
\n \n \n
\n Project settings\n
\n
\n Choose the preferences that fit your workflow.\n
\n \n
",
"description": "Switch between related views without leaving the page.",
"contract": "Use .tabs[data-tabs] with a direct .tab-list and direct section panels. Label the list with aria-label. Each native button needs a unique id and aria-controls matching one panel id. Keep buttons disabled and all panels visible in source; tabs.js enables controls and adds tab semantics only after validating references. Include tabs.css and tabs.js once. Arrow keys follow orientation and RTL; Home/End select first/last enabled tab. Automatic activation is default for local content; data-activation=manual moves focus only until Enter/Space. data-orientation=vertical uses Up/Down. data-tab-disabled keeps a tab unavailable; explain why visibly. data-tab-active chooses the initial enabled tab; a matching URL fragment takes precedence. Hash changes reveal a matching panel; selecting a tab does not rewrite browser history. Inactive panels are hidden immediately; panel form state is retained. Never nest controls in tabs. Shared 300ms color and hover-highlight transitions respect reduced motion and data-motion=none; focus and panel selection are immediate. No fetching, routing, persistence, or dynamic tab insertion is provided. Re-running the script does not duplicate listeners. Use ordinary links for page/section navigation, not tab roles. Keep essential content in HTML; no SEO score is guaranteed. For page sections use nav.section-nav[data-section-nav] with native fragment links and section-target targets. Add data-mobile=select for the native mobile dropdown. Keep all sections visible; aria-current=location follows scroll. Set --section-nav-offset on a common ancestor for fixed headers. Never use panel-tab roles for navigation.",
"usage": [
{
"title": "Navigate page sections",
"text": "For sections that remain visible, use section-nav with native links and section-target IDs. Add data-mobile=select for the mobile dropdown. Try the full-page example below the panel examples."
},
{
"title": "Group related views",
"text": "Use tabs for alternate panels. Keep ordinary links for page navigation or jumping between visible sections."
},
{
"title": "Connect each panel",
"text": "Match each button\u2019s `aria-controls` to a unique panel ID. Load the tabs script once; without it, all panels remain readable."
},
{
"title": "Choose the behavior",
"text": "Arrow keys move between tabs. Use `data-activation=\"manual\"` to require Enter or Space before switching panels. Home and End move to the first and last tab."
},
{
"title": "Make it yours",
"text": "Use `.tabs-line` for an underline or `data-orientation=\"vertical\"` for a vertical list. Shared motion respects reduced-motion preferences."
}
],
"javascriptBytes": 3368,
"url": "/components/tabs"
},
{
"id": "datepicker",
"name": "Date Picker",
"kind": "components",
"dependencies": [
"field",
"datepicker"
],
"html": "
\n \n
\n \n \n
\n
\n Choose a date or enter it directly. This example does not save it.\n
\n
",
"description": "Choose a date with a clear calendar or familiar native input.",
"contract": "Compose a labeled native input.input type=date inside datepicker[data-datepicker], with a hidden type=button data-datepicker-open. Include base, field and datepicker CSS plus deferred datepicker.js. Clicking the input or calendar button opens the picker; plain keyboard focus does not. Desktop input clicks preserve editing focus; mobile modal and button activation focus the calendar. Dismissal returns to the opener unless focus moved elsewhere. Keyboard instructions live in the documentation, not inside the calendar. Native entry remains available without JavaScript; hide the native calendar indicator only after enhancement; the optional calendar uses anchored nonmodal desktop dialog and a mobile modal below 480px, with immediate Escape and appropriate focus return. One date only, proleptic Gregorian years 0001\u20139999, ISO YYYY-MM-DD values with no time zone. Never parse localized text or convert date-only values through local Date constructors. Use min, max and step for date constraints; the calendar honors these and marks unavailable dates aria-disabled, keeping them navigable for context. Set consistent min/max limits; app/server validation remains required. Arrows move a day/week, Home/End a week edge, Page Up/Down a month and Shift+Page Up/Down a year. The six-row calendar includes muted, selectable adjacent-month dates, subject to the same limits. Month/year changes clamp the day for leap years and shorter months. Enter/Space selects and emits bubbling input/change; Backdrop clicks and Escape discard navigation. Native form reset restores the initial value. Disabled and readonly inputs cannot open the custom picker. Only one day is in the tab order. Dates, weekday names and heading use Intl with nearest lang and Gregorian calendar; Localize data-title, data-month, data-year and data-previous-month/data-next-month, data-previous-year/data-next-year, data-previous-years/data-next-years. Separate month/year buttons open 12-item selection grids with arrow/Home/End navigation; Page Up/Down changes year or 12-year page. Selecting either a year or month returns directly to the day calendar, preserving the other part where date limits allow. Weekday labels use Intl narrow forms with full names in column headers. Sunday starts the week; data-week-start=1 uses Monday. RTL reverses horizontal arrows. Date cells have 44px height; narrow calendars may have smaller widths but preserve spacing. Dialog is bounded by viewport and scrollable. Shared 300ms fade/4px slide honors reduced motion and data-motion=none; focus and selection are immediate. No package dependencies, requests, persistence, natural-language parsing, non-Gregorian calendar or arbitrary disabled-date callback. Custom time popup: use .datepicker[data-timepicker] with a native time input and hidden labeled button; datepicker.js enhances it. data-hour-format=12 enables AM/PM; default 24-hour. Native number inputs and chevron buttons apply valid changes immediately with input/change; invalid edits retain the last valid value. Escape/outside close. Localize data-title/hour/minute/second/increase/decrease/period/invalid. Pair with a labeled native input type=time for date-and-time, or use time alone with base and field CSS and no runtime. Native time values use HH:mm or HH:mm:ss; the enhanced text field follows the configured picker hour format, with validated text entry. step=60 selects minute precision and step=1 seconds. Preserve min/max/required, disabled/readonly, submission and reset. Application code owns time zones and daylight-saving ambiguity. For paired ranges, use data-date-range with data-range-start and data-range-end inputs and optional data-range-error message linked by aria-describedby. Enhancement combines the fields into one visible range button (data-range-label/data-range-placeholder localize its name/empty text); separate native fields remain form values and no-JavaScript fallback. One shared calendar: first select a draft start, then an end on or after it. Commit both inputs together only after the second selection; Escape/outside discard incomplete drafts. Same-day ranges are allowed. Localize data-start-prompt and data-end-prompt on the first datepicker wrapper. Typed reversed ranges set custom validity on the end and announce the error; values are never silently changed. data-range-message localizes the ordering error. Clearing and form reset update validation. Preserve native min/max/step and validate ordering on the server, including without JavaScript. Keep instructions in HTML; no SEO ranking guarantee. Test keyboard, touch, screen readers, zoom/reflow, forced colors, limits, step, reset and all palettes before release.",
"usage": [
{
"title": "Start with a real date field",
"text": "Use a visible label and `input type=\"date\"`. Clicking the field or calendar button opens the picker; Tab focus keeps direct keyboard entry available. The small calendar button is enabled by `datepicker.js`; native entry still works without it."
},
{
"title": "Make choosing easy",
"text": "Click the month or year separately to open a selection grid. Selecting a month or year returns directly to the calendar so you can choose a day. Arrows page through years in month view and groups of 12 years in year view. Muted dates belong to neighboring months and can also be selected. The calendar opens beside its field on desktop and as a compact modal on mobile. Arrows move by day or week; Home/End move to week edges. Page Up/Down changes month; hold Shift to change year. Enter selects. Escape or clicking outside closes without changing the value."
},
{
"title": "Choose a date range",
"text": "Wrap two date pickers in `data-date-range` and mark their inputs `data-range-start` and `data-range-end`. Use unique labels, IDs and names. JavaScript combines the fields into one visible range control and one shared calendar. The two native fields remain the submitted values and no-JavaScript fallback. The first selection starts a draft; the second commits both dates together. Escape or outside dismissal discards an unfinished draft. Same-day ranges are allowed. Typed reversed ranges receive native validation and an optional `[data-range-error]` live message; localize it with `data-range-message`. Clearing a date removes its ordering constraint. Native min/max/step stay intact. Without JavaScript, both fields still work; validate ordering on the server."
},
{
"title": "Explain the limits",
"text": "Set `min`, `max`, and `step` only when needed, and describe the allowed dates before entry. Mark required fields visibly and connect errors with `aria-describedby`."
},
{
"title": "Add time when needed",
"text": "Pair the calendar with a labeled `input type=\"time\"`, or use it alone with base and field styles. For a styled popup, wrap it in `.datepicker[data-timepicker]` with a hidden labeled button and include the Date picker styles and script. Use `data-hour-format=\"12\"` for AM/PM or omit it for 24 hours. Valid changes apply immediately; Escape and outside clicks close the picker. Invalid edits do not replace the last valid time. AM/PM and chevrons are disabled when their next change violates min/max/step; invalid typed entries show an error. Native entry works without JavaScript. Use `step=\"60\"` for minutes or `step=\"1\"` for seconds, with native `min`, `max`, and `required` constraints. The enhanced text field follows the picker\u2019s 12/24-hour format; submitted values use `HH:mm` or `HH:mm:ss`. Explain the scheduling time zone and resolve daylight-saving ambiguity in application code; a local date and time are not a UTC timestamp."
},
{
"title": "Keep dates as dates",
"text": "Read and submit `YYYY-MM-DD` values. A birthday or due date is not a timestamp; converting it through a time zone can shift the day."
},
{
"title": "Localize the whole experience",
"text": "Set `lang` and `dir`, translate the calendar action labels, and use `data-week-start=\"1\"` for Monday. The calendar uses Gregorian dates."
},
{
"title": "Know what is included",
"text": "This picker selects one date. Time-zone conversion, natural-language parsing, saving, and server validation belong to the application. Check assistive technology and mobile browsers for your audience."
}
],
"javascriptBytes": 0,
"url": "/components/datepicker"
},
{
"id": "slider",
"name": "Slider",
"kind": "components",
"dependencies": [
"slider"
],
"html": "
\n
\n \n \n
\n \n
",
"description": "Adjust a value within a defined range.",
"contract": "Set --slider-track to a color or gradient for a custom track, with a visible label describing its scale. Use .slider-field with a labeled native input type=range and explicit min, max, step and value. Optional output with matching for and data-unit displays the value when deferred slider.js is included. Native arrows, Home and End, disabled, form submission and reset remain available. Dispatch input after programmatic changes. No network or persistence. Keep help linked with aria-describedby; use a number input when precise typed entry is essential.",
"usage": [
{
"title": "Define a range",
"text": "Set min, max and step to meaningful values. Include a visible label and optional output with units."
},
{
"title": "Preserve native controls",
"text": "Arrow keys adjust the value; Home and End reach the limits. Native disabled, form submission and reset remain intact. Use a number input when exact typing is essential."
},
{
"title": "Show the value",
"text": "Load slider.js to synchronize output on input and form reset. Dispatch input after programmatic changes. The range works without JavaScript."
}
],
"javascriptBytes": 0,
"url": "/components/slider"
},
{
"id": "spinner",
"name": "Spinner",
"kind": "components",
"dependencies": [
"button",
"spinner"
],
"html": "
\n \n \n \n Loading\u2026\n \n
",
"description": "A quiet indicator for work in progress.",
"contract": "Include base and spinner CSS. Use .spinner, optional .spinner-small or .spinner-large, or --spinner-size for sizing. It inherits currentColor. Pair the decorative aria-hidden spinner with visible loading text in a role=status container. Do not add a second live region inside an existing status or toast. Application code inserts and removes the indicator as real work starts and finishes; initial static status content is not guaranteed to be announced. Use aria-busy on the region being updated and clear it on completion. Keep known progress in a native progress element instead. Continuous linear rotation takes three shared motion durations (900ms by default), a purposeful ongoing-work exception; reduced motion and data-motion=none show a static clock icon with unchanged status text. Never imply percentage progress or completion. No JavaScript, dependencies beyond base CSS, focusable elements or network requests.",
"usage": [
{
"title": "Explain the wait",
"text": "Keep short, visible status text beside the spinner. Hide the ring itself from assistive technology when the text describes it. Use one polite status region, not nested announcements."
},
{
"title": "Connect it to real work",
"text": "Show the spinner only while an operation is pending. Remove it on success or failure and provide the result. Dismissing a loading toast does not cancel its operation."
},
{
"title": "Keep progress honest",
"text": "A spinner indicates an unknown duration. Use a progress element when the percentage is known. Mark the updating content region aria-busy and clear that state when it is ready."
},
{
"title": "Respect motion preferences",
"text": "Reduced motion and data-motion=none replace the rotating ring with a static clock icon and preserve readable status. The spinner needs no JavaScript."
}
],
"javascriptBytes": 0,
"url": "/components/spinner"
},
{
"id": "toast",
"name": "Toast",
"kind": "components",
"dependencies": [
"button",
"spinner",
"toast"
],
"html": "\n Show Toast\n\n\n\n",
"description": "Brief feedback that keeps people in their flow.",
"contract": "Include base, button, spinner and toast styles plus deferred toast.js. Use one .toasts[data-toasts] region with a unique id and an accessible Notifications label. Declarative buttons start hidden and use data-toast-target, data-toast-title, optional data-toast-description, data-toast-tone and data-toast-duration. JavaScript reveals matching triggers. Place the region directly in body outside transformed or clipping ancestors. root.toast.show({title,description,tone,duration,urgent,action:{label,onClick}}) returns an id or null for invalid input or a full queue. update(id, options), dismiss(id), clear() manage messages. Action receives {id,dismiss}; application code owns real results and persistence. Titles/descriptions are rendered as text, never HTML. Default duration is zero (persistent); positive durations have a six-second minimum. Errors, loading messages and messages with actions remain until dismissed. Use tone:loading for the shared spinner; update the same id to success or error when work ends. Dismissal does not cancel the operation. Timers pause on pointer hover, focus within the toast and hidden documents, resuming remaining time. Maximum three visible and twenty total; overflow returns null so applications can keep a durable result elsewhere. Queued messages start their timer only when displayed. Updates reuse their place and restart the timer. Polite announcements are default; urgent:true explicitly opts into assertive announcements. Do not place live roles on the visual cards or their controls. Toasts never steal focus; Escape dismisses only when focus is inside a toast, returning to its connected origin. Dismiss buttons remain at least 44px. Default placement is bottom-center, set data-position to top-start, top-center, top-end, bottom-start, bottom-center or bottom-end. Legacy top means top-end. RTL mirrors start/end placement. data-dismiss localizes the close label. Shared 300ms opacity/transform entry respects reduced motion and data-motion=none; removal and focus are immediate. No packages, network, storage, promise tracking or background tasks. No-JavaScript triggers stay hidden; essential confirmation and errors belong in persistent page content. SEO belongs to documentation, not transient messages. Verify keyboard, focus return, queue pressure, timers, long text, RTL, narrow screens and all themes.",
"usage": [
{
"title": "Choose a placement",
"text": "Set `data-position` on the region: `top-start`, `top-center`, `top-end`, `bottom-start`, `bottom-center`, or `bottom-end`. The default is bottom-center. Start and end mirror in RTL. Choose one consistent position for each notification stream."
},
{
"title": "Use meaningful status icons",
"text": "Success uses a check circle, information an info circle, warning a triangle, and error an x circle. Shared SVG artwork comes from the icon catalog. Keep visible text alongside every icon; color alone must not convey the result."
},
{
"title": "Confirm a result",
"text": "Show a toast after an operation finishes. Keep important errors, receipts, and recovery steps visible in the page too. Toasts do not save or send anything."
},
{
"title": "Give people enough time",
"text": "Messages stay until dismissed by default. Timed messages last at least six seconds and pause on hover, keyboard focus, or a background tab. Errors and messages with actions stay visible."
},
{
"title": "Keep announcements calm",
"text": "Routine feedback is announced politely. Use `urgent: true` only for time-sensitive information that warrants interrupting a screen reader. A toast never moves focus on arrival."
},
{
"title": "Handle several messages",
"text": "Up to three messages are visible at once; additional messages wait their turn, up to twenty total. `show()` returns `null` when full. Update an existing message for progress instead of generating repeated notifications."
},
{
"title": "Use the keyboard",
"text": "Tab reaches actions and Dismiss. Escape closes the focused toast and returns focus to its origin when available. Reduced motion removes entry animation. Translate the region name, content, action labels, and `data-dismiss`."
}
],
"javascriptBytes": 0,
"url": "/components/toast"
},
{
"id": "color-picker",
"name": "Color Picker",
"kind": "components",
"dependencies": [
"button",
"field",
"select",
"color-picker"
],
"html": "
\n \n
\n \n \n
\n
\n Choose a color or enter a six-digit hex value, such as #294cda.\n
\n
",
"description": "A color swatch and hex value in one clear field.",
"contract": "Add data-swatch-only to hide the hex field after enhancement while retaining its full-picker swatch. Add data-hue-slider for an inline hue rail that preserves saturation and brightness, with data-hue for its accessible name. Add data-slider-swatch to show the rail beside its full-picker swatch without the hex field. Add data-slider-only to show only that rail after enhancement; the named hex input remains the form value and no-JavaScript fallback. Invalid hidden fields focus the rail; required slider-only inputs should start with a valid value. Dispatch input or color-picker-sync after programmatic changes. Use a labeled hex input inside .color-picker[data-color-picker] with a hidden type=button trigger marked data-color-swatch. Hex text is the named form value; use pattern=#[0-9a-fA-F]{6}, maxlength=7, and required when needed. Load base, field, select, and color-picker styles plus optional color-picker.js. JavaScript reveals and synchronizes the swatch; no-JavaScript text entry remains usable. A custom nonmodal dialog offers a pointer color area and equivalent native Hue, Saturation and Brightness sliders, and editable Hex, RGB, CSS, HSL, or HSB values. Switching formats preserves the color; the named form field always submits six-digit hex. Palette switches to all 209 source palette colors; selecting a shade returns to controls. Arrow keys navigate swatches, Home/End navigate a family, Ctrl+Home/End navigate all families. Color returns without changing the value. Escape returns focus; outside interaction dismisses. Values commit immediately. Opaque by default. Add data-alpha with maxlength=9 and a six-or-eight-digit hex pattern to allow opacity; submitted alpha uses #RRGGBBAA below full opacity and six-digit hex at 100%. RGB, HSL and HSB accept a fourth opacity value (0\u20131 or a percentage); CSS accepts hex, rgba() and hsla(). Palette and eyedropper preserve opacity. Add data-basic for only a hue slider, keyboard-focusable color area (no header, value editor or eyedropper); Escape or outside interaction closes it; left/right adjust saturation and up/down adjust brightness, with Shift for larger steps. Gradients and named colors are unsupported. Preserve disabled, readonly, reset, and native form validation. Optional empty values show a slashed swatch; typing invalid text does not change it. Give the swatch an independent accessible action name and associate visible format help with the text field. Programmatic value changes must dispatch input or color-picker-sync on the wrapper. Clicking the hex field opens the picker while preserving text focus; Tab focus alone does not open it. Keyboard Tab reaches the swatch and text separately. Localize data-title, data-close, data-hue, data-saturation, data-brightness, data-hex, data-palette and data-color. The custom dialog honors reduced motion and data-motion=none. Eyedropper appears only when the secure-context EyeDropper API exists. Explicit activation samples a screen color; cancellation preserves the value. Disabled state or closing aborts pending sampling. Localize data-eyedropper and data-sample-error. Formats are Hex, RGB, HSL, OKLCH and CSS token in that order. Tokens resolve against the bundled palette; unmatched custom colors display hex. OKLCH converts to the sRGB hex form value. No persistence or network requests. Verify contrast in the consuming design; selecting a color does not guarantee accessibility.",
"usage": [
{
"title": "Offer direct hue adjustment",
"text": "Add data-swatch-only for a swatch that opens the full picker without displaying the hex field after enhancement. Add data-hue-slider for a compact inline hue rail alongside the swatch and hex field. Add data-slider-swatch for a single row with a hue rail and a swatch that opens the full picker. Add data-slider-only to display just the rail after enhancement. data-hue supplies its accessible name. Hue preserves saturation and brightness; start with a chromatic color for visible changes. The original hex field remains the named form value and no-JavaScript fallback. Native arrows, Home and End adjust hue."
},
{
"title": "Keep the value together",
"text": "Use one labeled `color-picker` wrapper for the swatch button and editable hex value. Only the text field needs a form name."
},
{
"title": "Choose or type",
"text": "Click the swatch or hex field to open the picker. Clicking the field keeps text editing focused; Tab focus alone does not open it. Use the color area with a pointer or the labeled sliders with arrow keys. Escape closes the picker and returns focus. Choose Hex, RGB, CSS, HSL, or HSB to edit in that format; the form value remains hex. Changes apply immediately. Eyedropper samples a screen color in supporting secure browsers; Escape cancels without changing the value. Palette shows the full color scales; choose a shade to return, or choose Color without changing it. Arrow keys move between shades and families."
},
{
"title": "Handle optional colors",
"text": "Omit `required` to allow an empty value. Clear the hex field to remove the color. A slash marks an empty swatch; invalid text never silently replaces the last valid color."
},
{
"title": "Preserve native behavior",
"text": "Use disabled, readonly, form reset, and linked help. Update values through input events or `color-picker-sync` after programmatic changes. Validate submitted colors on the server."
}
],
"javascriptBytes": 0,
"url": "/components/color-picker"
},
{
"id": "password",
"name": "Password",
"kind": "components",
"dependencies": [
"field",
"password"
],
"html": "
\n \n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n
\n Use a sample password here. This example does not send or save it.\n
\n
",
"description": "Private text entry with an accessible visibility control.",
"contract": "Use a labeled native input type=password inside password[data-password], with class=input, unique id, name, and autocomplete=current-password for sign-in or new-password for creation. Keep paste, autofill, password managers, selection and native validation available; do not trim or transform values. Include a hidden type=button with data-password-toggle, matching aria-controls, and localized data-show/data-hide labels. The deferred password script reveals the button and toggles the existing input without copying its value, preserving selection and button focus. The decorative eye/eye-off icon and accessible action label change between Show Password and Hide Password; no aria-pressed is needed for this changing-label action. Without JavaScript the field remains masked and editable, and the toggle remains hidden. Disabled inputs and disabled fieldsets disable the toggle; readonly values remain focusable and revealable. Reset and pagehide remask the input. Do not serialize real passwords into HTML, URLs, logs, analytics, or browser storage. No strength scoring, authentication, persistence, requests, or security guarantee is provided. Application code owns password policy, server validation and errors; use visible requirements and aria-describedby, mark required visibly and natively, and clear aria-invalid with errors. Never use the reveal control as a submit button. Support RTL, 16px text, 44px targets, responsive wrapping, native forced colors, immediate focus and visibility changes, and shared reduced-motion safeguards. Password masking is visual privacy, not encryption; use secure application transport and credential handling.",
"usage": [
{
"title": "Use the right autocomplete",
"text": "Choose `current-password` for sign-in and `new-password` for creation or changes. Keep paste and password managers available."
},
{
"title": "Make visibility explicit",
"text": "The button changes between Show Password and Hide Password. It changes the existing input and never submits the form."
},
{
"title": "Keep the fallback useful",
"text": "Start with `type=\"password\"` and a hidden toggle. Without the component script, people can still enter a masked password."
},
{
"title": "Explain requirements",
"text": "Your application owns password rules and validation. Connect help and errors with `aria-describedby`; clear `aria-invalid` when corrected."
},
{
"title": "Handle credentials responsibly",
"text": "Do not put real passwords in page markup, URLs, logs, or browser storage. This component neither saves nor sends the value."
},
{
"title": "Know what is included",
"text": "Reset and leaving the page remask the field. Strength scoring and authentication are separate application responsibilities."
}
],
"javascriptBytes": 0,
"url": "/components/password"
},
{
"id": "switch",
"name": "Switch",
"kind": "components",
"dependencies": [
"switch"
],
"html": "",
"description": "Clear on/off settings with native keyboard behavior.",
"contract": "Use label.switch containing input type=checkbox role=switch and a stable span label naming the setting. Native checked exposes the on/off state; do not add aria-checked, custom key handlers or tabindex. Use switches for binary settings, checkboxes for consent or selections, and radio buttons for mutually exclusive choices. Keep the label unchanged when toggled. No mixed or readonly state. Supply name and value; only checked enabled switches submit. Native checked sets initial state and form reset restores it. Use disabled or disabled fieldset with a visible explanation. Tab focuses and Space toggles; the full label is at least 44px tall around a 44 by 24px track. Position and color both indicate state. Link separate help via aria-describedby and keep links/buttons outside labels. The 16px thumb moves 20px over the shared 300ms duration; native state changes immediately. RTL reverses the travel. Reduced motion and data-motion=none remove animation; forced colors restores the native control. No runtime JavaScript, persistence, requests or automatic setting application is provided; application change handlers own saving, failure rollback and status messages. Demo changes are temporary. Do not claim success until saving completes. Keep text in source HTML, allow wrapping and verify focus, narrow layouts and all palettes. No SEO ranking guarantee.",
"usage": [
{
"title": "Use it for a setting",
"text": "Switches express on or off. Use a checkbox for consent or selections, and radio buttons to choose one of several options."
},
{
"title": "Keep the label stable",
"text": "Name the setting, such as Project notifications. Do not change the name to match its state; the native control announces on or off."
},
{
"title": "Keep behavior native",
"text": "Use `input type=\"checkbox\" role=\"switch\"` inside `label.switch`. Tab focuses it and Space toggles it. Do not duplicate checked state with ARIA."
},
{
"title": "Explain unavailable settings",
"text": "Use native `disabled` and visible help text. Link descriptions with `aria-describedby` and keep other controls outside the label."
},
{
"title": "Connect saving deliberately",
"text": "The component changes local state only. Your application owns saving, failure handling, and confirmation messages. Checked, enabled switches submit their name and value."
},
{
"title": "Respect motion preferences",
"text": "The thumb uses shared 300ms motion and reverses in RTL. Reduced motion and `data-motion=\"none\"` make it immediate."
}
],
"javascriptBytes": 0,
"url": "/components/switch"
},
{
"id": "textarea",
"name": "Textarea",
"kind": "components",
"dependencies": [
"field",
"textarea"
],
"html": "
\n \n \n \n
\n Include goals, context, and any important details.\n
\n
",
"description": "Room for longer thoughts, with native editing and clear guidance.",
"contract": "Use a native textarea with class=\"input textarea\" inside field. Associate a visible label via unique for/id and help or errors via aria-describedby. Use name for submission and rows for initial height; default width is fluid, minimum height 96px, font size 16px, and vertical resizing remains available where the browser supports it. Content scrolls when it exceeds the resized area; do not clip overflow or animate height. Initial values go between textarea tags, never in a value attribute; escape untrusted content and use the value property for application updates. Preserve newlines, paste, selection, undo, IME composition and native Tab behavior. Enter inserts a newline, never auto-submits. Disabled controls are unfocusable and omitted from submission; readonly controls remain focusable, copyable and submitted. Mark required visibly and natively; use maxlength only for a real constraint and explain it before typing. Native length constraints count UTF-16 code units, not user-perceived characters. aria-invalid communicates an application-owned error and does not enforce validity; clear errors after correction and validate on the server. Form reset restores the initial text. Shared 300ms color feedback honors reduced motion and data-motion=none; focus is immediate. No runtime JavaScript, automatic growth, character counter, rich-text editor, persistence or requests are included. Keep labels and instructions in source HTML; there is no SEO ranking guarantee. Test long text, RTL, keyboard editing, zoom, narrow screens and all theme palettes.",
"usage": [
{
"title": "Give it a clear purpose",
"text": "Use a visible label and connect help text with `aria-describedby`. A placeholder is an example, never a replacement for the label."
},
{
"title": "Leave room to write",
"text": "Set `rows` for the starting height. Textarea fills its container and allows vertical resizing where supported. Automatic growth is not included."
},
{
"title": "Preserve normal editing",
"text": "Enter adds a new line. Keep paste, selection, undo, and keyboard navigation native. Put initial text between the tags, not in a value attribute."
},
{
"title": "Explain constraints and errors",
"text": "Show required status and length limits before typing. Associate useful errors and clear `aria-invalid` when corrected. Validate on the server too."
},
{
"title": "Choose the right state",
"text": "Disabled fields cannot be edited, focused, or submitted. Read-only fields remain focusable, copyable, and submitted."
},
{
"title": "Keep responsibilities clear",
"text": "Your application owns saving, validation messages, and any character counter. Styling does not store or send the text."
}
],
"javascriptBytes": 0,
"url": "/components/textarea"
},
{
"id": "radio",
"name": "Radio",
"kind": "components",
"dependencies": [
"radio"
],
"html": "",
"description": "One choice from a clear, related group.",
"contract": "Use fieldset.radio-group with a visible legend and label.radio wrapping each native input type=radio and span. Use the same nonempty name and distinct values within a group; unrelated groups need distinct names in the same form owner. Only one checked initial option per group; omit checked when a deliberate choice is required. Labels provide 44px targets around 20px controls. Tab enters/leaves the native group, arrow keys move and select enabled options, and Space selects; do not override native keyboard behavior or add roles, aria-checked or tabindex. No mixed state or readonly state exists. Use disabled on individual inputs or the fieldset, with a visible explanation. Required on a group member requires a selection; repeat it consistently on the group inputs and mark the legend required. Associate visible help/errors using aria-describedby on inputs; aria-invalid is application-owned and must clear with corrected errors. Only the checked enabled value submits; form reset restores initial checked state. Never auto-submit or navigate on selection. Keep links and other controls outside labels. Text wraps and logical spacing supports RTL. Shared 300ms color and dot opacity transitions honor reduced motion and data-motion=none; forced colors restores native appearance. No runtime JavaScript, requests, persistence, validation controller or SEO ranking guarantee. Keep labels and content in HTML; validate submitted values on the server.",
"usage": [
{
"title": "Name the group",
"text": "Use `fieldset.radio-group` and a visible legend. Wrap each radio and its text in `label.radio` so the whole label is clickable."
},
{
"title": "Keep choices together",
"text": "Give related inputs the same `name` and different `value` attributes. Use a different name for each independent group."
},
{
"title": "Choose an initial state",
"text": "Add `checked` to one sensible default, or leave the group unselected when the user must decide. Radio buttons have no mixed state."
},
{
"title": "Explain validation",
"text": "Mark required groups in the legend and add `required` to their inputs. Connect visible errors with `aria-describedby`; clear `aria-invalid` when corrected."
},
{
"title": "Preserve native behavior",
"text": "Arrow keys select within the group, Space selects, and Tab leaves it. Form reset restores the initial choice. Only the selected enabled value submits."
},
{
"title": "Keep choices predictable",
"text": "Do not navigate or submit on selection. Keep links outside labels, explain disabled options, and use checkboxes when several choices are allowed."
}
],
"javascriptBytes": 0,
"url": "/components/radio"
},
{
"id": "checkbox",
"name": "Checkbox",
"kind": "components",
"dependencies": [
"checkbox"
],
"html": "",
"description": "Independent choices with clear labels and native behavior.",
"contract": "Use label.checkbox containing one native input type=checkbox and a span label. The whole label is a 44px-minimum target; the visual control is 20px. Give inputs a name and explicit value for form submission. Only checked enabled boxes submit; unchecked and disabled boxes are omitted. Use checked for initial state and native disabled or fieldset disabled, never aria-disabled alone. Use fieldset.checkbox-group with legend for related choices. Required applies to an individual checkbox, not at-least-one selection in a group. Associate help and visible errors via aria-describedby; set aria-invalid=true only after validation and clear it when corrected. Do not nest links or buttons in the label. Keyboard Tab and Space, form reset, focus and change events remain native; no redundant role or aria-checked. Set the JavaScript indeterminate property for a mixed state; it is not an HTML attribute and does not change checked/submission. Application code must derive mixed state from children and restore it after reset if needed. Use shared 300ms color and mark-opacity transitions; no movement or delayed state changes. Reduced-motion and data-motion=none are respected; forced colors restores native appearance. No runtime, requests, persistence, group controller, or SEO guarantee is provided.",
"usage": [
{
"title": "Make the label clickable",
"text": "Wrap one native checkbox and its text in `label.checkbox`. Keep links and other controls outside the label."
},
{
"title": "Group related choices",
"text": "Use `fieldset.checkbox-group` and a descriptive legend. Each choice stays independent; use radio buttons for exactly one choice."
},
{
"title": "Explain validation",
"text": "Connect help or errors with `aria-describedby`. Native `required` means this particular box must be checked, not any one box in a group."
},
{
"title": "Understand form values",
"text": "Only checked, enabled boxes submit their name and value. A native form reset restores the initial checked state."
},
{
"title": "Use mixed state carefully",
"text": "Set `input.indeterminate = true` in JavaScript. It describes a partial group selection; it is not a third submitted value or an HTML attribute."
},
{
"title": "Keep motion consistent",
"text": "Color and checkmark opacity use the shared 300ms timing. Reduced-motion preferences and `data-motion=\"none\"` disable transitions."
}
],
"javascriptBytes": 0,
"url": "/components/checkbox"
},
{
"id": "example",
"name": "Example",
"kind": "components",
"dependencies": [
"example",
"button",
"disclosure"
],
"html": "\n
\n",
"description": "A reusable live preview with collapsible source code.",
"contract": "Use section.example with an accessible name, .example-frame, .example-preview, and .example-content. Place actual component markup in the preview; menus and popovers use the page viewport and may extend beyond its border. Do not add overflow clipping or transforms to the frame. Set data-width=narrow for form controls, compact for small controls, or omit it for full width. Add a native details/summary and .example-code containing escaped code in pre/code; make long code scrollable and label its focusable pre. .example-toolbar arranges optional actions. This component needs no JavaScript. Include the demonstrated component CSS/JS separately, once per page. Give every example unique IDs, label/control references and radio names. It is for trusted component markup, not arbitrary user code. Keep full-page layouts and viewport-boundary demonstrations in sandboxed iframes.",
"usage": [
{
"title": "Show working components",
"text": "Render trusted component markup in the live preview. Load its shared styles and runtime once on the page."
},
{
"title": "Keep overlays free",
"text": "Menus, tooltips and dialogs should extend beyond the example border. Do not clip the preview; reserve iframes for page-layout and viewport-boundary demos."
},
{
"title": "Keep examples independent",
"text": "Use unique IDs and matching labels, ARIA references and radio names. Escape the source code inside pre/code."
}
],
"javascriptBytes": 0,
"url": "/components/example"
},
{
"id": "select",
"name": "Select",
"kind": "components",
"dependencies": [
"select"
],
"html": "
\n \n
\n \n
\n \n Choose your current project stage.\n \n
",
"description": "Animated choices with optional search and native form support.",
"contract": "Wrap a labeled single native select in .select-control and load select.css plus deferred select.js. The runtime adds a themed combobox and animated top-layer listbox while the select retains name, value, required validation, disabled state, option groups, reset and form submission. Search appears automatically for ten or more visible options. Add data-select-search to enable it for shorter lists, or data-select-search=false to disable it; customize data-search-placeholder and data-empty-text. Arrow keys navigate enabled options, Enter/Space commits, Escape cancels, Tab dismisses, and select-only controls support type-ahead. Search accepts text and Arrow keys/Enter choose a result. Outside pointer/focus dismisses without changing the value. Options have 44px touch targets and scroll within viewport bounds. Opening and closing use shared motion tokens; reduced motion and data-motion=none disable animation. Native select remains the no-JavaScript/unsupported-Popover fallback; add data-select-native to opt out. Multiple and size listboxes stay native. Use visible labels and aria-describedby for help/errors. Set aria-invalid only with a presented error. Programmatic changes should emit input/change; layoutSelect.refresh() initializes newly added controls, also discovered automatically. Removed controls release listeners. No remote requests, rich HTML options, or virtual scrolling.",
"usage": [
{
"title": "Offer a clear choice",
"text": "Use Select for one value from a known list. Keep option names short and distinguishable. Search appears automatically for ten or more options. Add `data-select-search` to enable it for shorter lists, or `data-select-search=\"false\"` to disable it."
},
{
"title": "Label the field",
"text": "Associate a visible label with the select ID. Put help text outside `select-control` and connect it with `aria-describedby`."
},
{
"title": "Explain errors",
"text": "Use `required` for native validation. When presenting an error, add `aria-invalid=\"true\"` and reference the visible error message. Do not rely on color alone."
},
{
"title": "Let the browser help",
"text": "Load `select.js` for themed animated menus, keyboard navigation and optional search. Native form submission and reset remain intact. Without JavaScript or Popover support the native picker remains available."
}
],
"javascriptBytes": 0,
"url": "/components/select"
}
]
}