Skip to content

README.md

Latest commit

 

History

History
60 lines (51 loc) · 4.62 KB

README.md

File metadata and controls

60 lines (51 loc) · 4.62 KB
Raw

UI8Kit primitives — documentation

The single, exhaustive home for the 19 UI8Kit primitives (plus the React-only Slot). Sites, the ui8kit CLI and the registry repos link here instead of copying it. Part of the UI8Kit 3 ecosystem — see the ecosystem block in the repo README.

How the docs are organized

Path What Source
primitives/ one page per primitive: purpose, props, variants, children, ARIA, <Name>Classes escape hatch, rendered DOM per state, one snippet per runtime generated by bun run docs (except the Notes prose block)
runtimes/ per runtime: install, children mechanism, deviations from React, helpers hand-written
contract.md DOM / token / ARIA parity rules every primitive and runtime follows hand-written
primitives/slot.md React Slot behind asChild hand-written

Runtimes: React · Vue 3 · Svelte 5 · SolidJS · Web Components · Go templ · Twig · Latte · Jinja2

Primitives

Primitive Parts Summary
Box Box Box is the polymorphic structural primitive. tag accepts HTML5 structural
Text Text Text is the polymorphic text primitive. tag accepts HTML5 text elements
Button Button Button triggers an action. With href it renders an anchor (navigation that
Link Link Link renders a semantic anchor for navigation. Use Button for actions
Label Label Label names a form control
Form Form Form is the native . Submission, validation and state are the consumer's;
Input Input Input is a single-line native form control (checkbox/radio have their own primitives)
Textarea Textarea Textarea is a multi-line native text field
Select Select, SelectOption, SelectOptGroup Select is a native dropdown. Flat options come from the Options list;
Checkbox Checkbox Checkbox is a native input[type=checkbox]; pair it with Label
Radio Radio Radio is a native input[type=radio]; pair it with Label
Switch Switch Switch is an on/off toggle: button[role=switch] with aria-checked
Image Image, Picture, Source Image renders img, picture, and source. Alt is required; pass an empty
Icon Icon Icon is a sized frame for a consumer-supplied glyph (svg, sprite, font)
Dialog Dialog Dialog is the native . Opening/closing (showModal) is the consumer's
Disclosure Disclosure, Summary Disclosure is native details/summary. name groups exclusive accordions
Meter Meter Meter is a native gauge for a known range (value/min/max)
Progress Progress Progress is native task progress (value/max); omit value for indeterminate
Separator Separator Separator is the native
(implicit role=separator). Vertical adds
Slot Slot React-only composition helper behind asChild (hand-written page)

Generated vs hand-written

  • bun run docs rewrites docs/primitives/<brick>.md from bricks/*/*.def.ts (props, enums, defaults, recipes, render tree) and bricks/*/*.data.json (showcase fixtures), plus the index table above. Hand-written notes go only between <!-- ui8kit-docs:prose:start --> and <!-- ui8kit-docs:prose:end --> in a primitive page — they survive regeneration.
  • Rendered HTML is the canonical renderer's output for the same fixture matrix the parity suites run (defaults, showcase fixtures, every enum value, every boolean); usage snippets are built with the parity suites' own per-runtime prop translators from the same fixtures, and tests/docs.test.ts renders every JS-runtime snippet's props and checks the documented HTML.
  • bun run docs:check fails when the generated parts are stale; it is part of bun run verify.
  • Everything else under docs/ is hand-written.

Agents: read docs/primitives/<name>.md before using a primitive.