| Reference | Value |
|---|---|
| Subject and boundary | @yesid/ui: primitives, brand components, page frames, site shell and head, shared state and class merging. What the package renders and what the caller must supply. |
| Verified source | UI README, export map, cn/index.ts, API report, product guide at tag v0.40.0. Verified tag v0.40.0, commit 43bba26a73dd0f7aa01cb7c8f37d697734b367ad, checked 2026-11-10. The SiteHeader row and the Page edges, reading and listing section are verified at tag v0.51.0, commit 4a05ca454fbf6c2bc3fb7f92b07f6e29ba4621ab, checked November 19, 2026. |
| Support state | Supported UI contracts in published v0.40.0. Products compile the source and verify their own integrations. |
| Subpath | Contents |
|---|---|
| Primitive families | 12 families: Badge, Button, Card, Collapsible, Combobox, Footer, Resizable, Scroll Area, Separator, Sheet, Skeleton and Tabs. Import the owning subpath. Card exports only Card and Root; use ordinary markup inside it. |
./brand, ./blueprints |
Brand components including SectionsToggle, CollapsibleSection, TOC/filter families, createSectionJump, useSectionJump and createNavigationLifecycle; blueprint drawings. |
./layout |
SiteRoot, SiteHeader, SiteFooter, ListingFrame, DetailFrame, ArticleHeader, ErrorPage, data-page parts (Surface, Masthead, Breadcrumb, ControlsRail, DashboardGrid, SurfaceRail). |
./table, ./feedback |
DataTable; StateNotice. |
./state |
theme, sections, desktop, clock, persisted, createLocaleContext. |
./head, ./boot.json |
SeoHead, injectThemeBoot; the boot script's CSP hash. |
./cn |
cn, configureUi, merger factories and prop helper types. |
./base.css |
Opt-in shared base layer. It imports tw-animate-css (the Sheet animation styles), the token theme, tap feedback and Lenis CSS. |
Import @yesid/ui/station-tabs.css after base.css. Apply station-tabs to the rail and station-tab to Tabs triggers or native links. Active state uses data-state="active" or aria-current="page". The stylesheet owns the signage look only: active weight 700, inactive primary-foreground ink, full-strength hover with a 3px bottom rule, token tap height and a 2px current-color inset focus outline. The independent variables are --station-tab-active-weight, --station-tab-ink and --station-tab-hover-rule-color. Products own scrolling, centering, swipe guards, routing, geometry and copy. Product opacity effects must preserve rendered contrast. Source: station-tabs.css.
| Contract | Rule |
|---|---|
| Element split | Button and Badge discriminate on href: null or undefined renders button/span, any string (including "") renders an anchor. Each branch exposes its real element's ref, events and attributes and rejects the other branch's attributes. |
| Fixed content | ChevronToggle, SectionLabel, StopLabel and TerminalCursor reject children. CollapsibleContent keeps children but hides the bits-ui child hook. |
| Delegated vs native | Separator default delegates to bits-ui; hazard and gradient render native divs. |
| Combobox | Bindable nullable value and open. The caller supplies options, labels, folded search haystacks, the fold function and all accessible copy; filtering is token-AND. Closing resets the query, clearing commits null. Public names are Combobox, ComboboxOption, ComboboxProps, data-slot="combobox". |
| Sheet detents | Sheet.Content opts into draggable bottom heights with detents: at least two ascending stops { id, size, label } in px or % (as dvh) and a caller handleLabel. bind:detent holds the id; ondetentchange fires only for user changes; callers own persistence. No drag-to-dismiss; reduced motion snaps instantly. A touch drag on the handle continues past the touched child's implicit pointer capture (#208). modal={false} removes the overlay, focus trap and scroll lock. |
| Tap size | Some controls enforce the minimum through var(--size-tap-min), which the imported tokens stylesheet sets to 44px, including Combobox, SliderButton, ToggleChip, Wordmark and footer links. Button does not: default is h-8, small is h-7, and only icon-tap is 44px. Every other target size is the caller's. |
| Copy | Caller-owned labels and accessible names. StopLabel defaults its prefix to ARRÊT. Sheet Content requires localized closeLabel whenever its close button can appear; only literal showCloseButton={false} permits omitting the label. |
Family-level compatibility seams (Badge number size, Button press behavior, Card bevel, Collapsible scaffold and Tabs geometry) are listed in the UI README. Component props and variant types are public; variant class factories are internal. A product keeps a local adapter only where a live consumer contract requires it.
stateDiagram-v2
[*] --> Unlocked
Unlocked --> Configured: configureUi(vocab) returns initialized
Unlocked --> DefaultLocked: first cn() call
Configured --> Configured: equivalent configureUi returns unchanged
DefaultLocked --> DefaultLocked: empty configureUi returns unchanged
Configured --> Error: conflicting configureUi throws
DefaultLocked --> Error: custom configureUi throws
| Rule | Detail |
|---|---|
| Two stages | Package tailwind-variants definitions merge with the base vocabulary; the caller's class merges through cn, where product vocabulary applies. |
| Scope | One configuration per loaded ESM module graph. Client bundle, each SSR worker, separately bundled copies and HMR-recreated graphs each initialize their own. No reset API. |
| Boot | One shared initializer imported from both hooks.client.ts (ClientInit) and hooks.server.ts (ServerInit), never a layout script. Initialize before any primitive renders. |
| Vocabulary | Fixed application text and colors names only; never derived from request, tenant, user or locale. Arrays are deduplicated and order-insensitive. |
| Base vocabulary | Every generated text token is a font-size name in the base merger; a UI test enforces parity with tokens.json. |
| Part | Contract |
|---|---|
| Page skeleton | SiteRoot, then SiteHeader (skip link to #main, then the banner), <main id="main">, then SiteFooter outside main. The product renders main and its routes. |
SiteRoot |
Adopts the boot theme, starts Lenis on mount (smoothScroll, scroller), and keeps <html lang> current. It renders no wrapper. theme.init() repaints every tab icon with the yesid mark in --primary even on first load without a theme change. |
SiteHeader |
Floating pill with a bits-ui Dialog menu. Create createNavigationLifecycle({ beforeNavigate, onNavigate, afterNavigate }) once in the persistent app layout and pass it as navigation. Kit 3 omits subscribeNavigation; direct language switches preserve the menu, eventless redirects close it without locale refocus. All header labels and language autonyms come from local app copy. Nav text keeps one size at every width: links 16px, wordmark 18px. The theme and language toggles stay in the pill at every width (D19). Links show from 375px of header width (default priority: 1), priority: 2 from 600px and priority: 3 from 1024px. These tiers are static container-query rules in em, so they hold before hydration, after it and without JavaScript, and linkTiers raises the priority 2 or 3 width for a wider brand. A link also needs the pill to fit its header with 4px to spare, measured from the real labels; a whole priority leaves at a time, and links that do not fit move to the menu. Keep every header destination in menuItems, or in menuGroups, whose headed groups lay out as columns from 768px and as one column below it. Every pill divider, including ProductBrand's, takes --nav-split-space on both sides. |
| Theme and sections boot | Put %yesid.themeBoot% before %sveltekit.head% and page content; apply injectThemeBoot in transformPageChunk and keep component CSS. It sets theme and section geometry before paint, reads sections-choice and handles rejected cross-document view transitions. Hydration adopts the geometry. The boot asset identity and hash-mode CSP requirements are in the security leaf. |
SeoHead |
Writes title, description, canonical, alternates, Open Graph, Twitter and one JSON-LD @graph from resolved values. Without canonical it writes no canonical, og:url or hreflang. description also accepts a resolveShareCopy selection from @yesid/seo-kit/share-copy; meta, Open Graph and Twitter descriptions use its bounded description. |
theme |
Dark default, ignores system preference, persists under theme, sets data-theme, updates theme-color and icon links, fires themechange. |
sections |
Actions for mounted content sections: count, allCollapsed, collapseAll(), expandAll() and toggle(). Bulk actions write the origin-wide sections-choice preference. On pages with SectionsToggle and at least two content sections, a first visit is expanded with a neutral control; after Collapse all the control is orange, with default activeEffect="glow". Excluded panels use their own defaults; the TOC starts open. |
persisted(key, initial) |
Tab-scoped sessionStorage under persisted:<key>; locale-free values only; returns the seed during SSR. |
desktop, clock, createLocaleContext |
1024px media query (false during SSR); one shared ticking clock with a server-time anchor; one locale context per app. |
| Frame | Contract |
|---|---|
ListingFrame |
From 1024px the filter panel is visible, sticky and keyboard-reachable before hydration and without JavaScript. Below 1024px a closed panel is visibility: hidden (never inert) and opening it needs JavaScript. onHeaderMount returns its cleanup. Reads --chrome-offset. |
DetailFrame |
Header, toolbar, optional rails, centre and after. toc tracks active entries and can land fragments. Supply both toc.openAria and toc.closeAria or neither. A mobile pill needs both labels, nonempty pill entries and no custom rail; omitting labels preserves tracking and fragments. Share one useSectionJump(afterNavigate) controller as toc.navigation with TocNav. Below 768px, top-level section cards in the centre column sit 8px from the screen edges instead of the 24px page gutter. |
ArticleHeader, ErrorPage, data-page parts |
Shared composition; the app keeps its copy, <svelte:head>, data and routing. |
| Part | Contract |
|---|---|
PageSections, PageSection |
One boundary between registered sections, never after the last, so nothing sits before the footer. divider sets it for the page: dimension (default, the drafting line), hand-drawn or hazard. The hand-drawn edge is an orange pen stroke in the blueprint ink; boundaries alternate four and five tapered strokes and overlay the shared edge of adjacent sections with zero layout height. yesid.dev's pages pass divider="hand-drawn". |
ArticleHeader |
Both presentations end with the same hand-drawn edge in the article-header-boundary slot, spanning the header with no layout height. DetailFrame hides its own rule when the header supplies the edge; inside PageSections the edge joins the page's alternating stroke sequence. |
SiteFooter |
edge draws the top edge: street (default, a dashed yellow and white road marking) or hazard, the diagonal yellow and black hazard strip. yesid.dev, Transit and yesid.login pass edge="hazard". Its brand snippet takes ProductBrand ("yesid. |
TerminalPanel, CodeBlock |
rule sets the line under the title bar: hazard (default), dimension or line, one solid yellow line (--accent) that a footer boundary repeats. The terminal-rule-line class gives server-rendered terminals the same line. |
ReadingFrame (Experimental) |
The calm frame for legal pages and long prose: an article with a sentence-case h1, an optional updated date, optional summary, contents and body on a 65 to 70 character measure. sections with contentsLabel render contents as orange underlined links; contentsRule="hand-drawn" draws the contents' top and bottom boundaries with the shared hand-drawn stroke (default line). |
ListingRail |
The listing pages' centred left title column with both four-dot clusters and the accent; ListingFrame uses it. On a standalone page it is the real heading (default h1, titleId) and reads horizontally below 1024px, where the dots and accent hide. clipAtHeader={false}, also accepted by RailTitle and ListingFrame, lets the rail title leave with its section instead of being clipped at the header. |
FilterGroup |
Single choice with an "All" reset. selectedStyle="consistent" gives the choices and the reset the same filled orange selection, with radio semantics as the non-colour cue; legacy is the default. |
StateNotice |
The positive, warning and error tones tint the glyph with --success, --accent-text and --destructive: interface feedback colours, never the transport status scale. |
CollapsibleSection owns page registration; SectionCard owns rendering. SectionsToggle controls at least two registered collapsible content sections; its server markup is present and hidden below that threshold. A control panel passes independent to stay outside bulk actions, counts and content-TOC active tracking. The TOC starts open, with its own independent toggle. Filter groups, listing panels, static cards and independent panels, including map tools, use their own state and actions. The generic persisted store supports other product state.