Skins

Skinning Control UI

Author complete token-driven Control UI skins with slots, adornments, motion controls, and one shared component source.

Not sure a skin is even the right tool? The customization ladder in the Architecture guide places every “make it different” request on one of eight rungs — with what each rung costs an app that never uses it. This page picks up once the answer is a skin.

Where skin values live

One owner for each visual decision.

theme tokenGlobal semantic color, radius, type, and motion values live in theme.css and feed every recipe.

component knobA component-specific visual is re-valued through its registered --component-* property in scoped skin.css.

custom CSSUse scoped skin.css for pseudo-elements, keyframes, native chrome, relational selectors, and uniform semantic families.

neverDo not repaint a recipe-owned property directly or invent a second variable for a value the component knob contract already exposes.

The token contract

Every custom property a skin may re-value, rendered straight from lib/theme-contract.ts — the same module the coverage test enforces, so this reference can never drift from the CSS.

Core — the 25 tokens a skin typically re-values first

--backgroundColorBase surface color (panels, bubbles read it via bg-background).

--foregroundColorDefault text color on --background.

--cardColorCard surface; sits on --background in light, one ramp step above it in dark.

--card-foregroundColorText color on --card.

--popoverColorFloating surface base (popover / menu / select / dialog).

--popover-foregroundColorText color on --popover.

--primaryColorTHE brand color; primary action surfaces route through it.

--primary-foregroundColorText color on --primary.

--mutedColorSubdued fill for quiet surfaces.

--muted-foregroundColorSecondary / meta text color.

--secondaryColorSecondary action fill (assistant bubble in chat skins).

--secondary-foregroundColorText color on --secondary.

--accentColorHover / selection highlight fill.

--accent-foregroundColorText color on --accent.

--destructiveColorDestructive action color.

--destructive-foregroundColorText color on --destructive.

--borderColorHairline border color (carries --ring-opacity).

--ringColorRing palette color; --focus-ring derives from it at 70% alpha, so a skin whose ring loses 3:1 there (a saturated accent or a softened halo) must set --focus-ring.

--canvasColorThe page paper the scene/panels float on; same ramp step as --background by default, skins may drop it below.

--font-sansTypographyTypeface for the whole UI.

--font-monoTypographyMonospace face (code, kbd).

--radiusRadiusTHE single radius knob; the whole scale multiplies from it.

--duration-fastMotionFast tempo for press feedback and small state transitions; frequent hover paint is instant.

--duration-baseMotionBase tempo (menus, indicators).

--duration-slowMotionSlow tempo (panel/message entrances).

Derived — optional overrides123 tokens with a core default; re-value one in theme.css only to diverge

--primary-textColorReadable brand text color on base and card surfaces; --primary at ramp step 11.

--destructive-textColorReadable destructive text color on base and card surfaces; --destructive at ramp step 11.

--success-textColorReadable success text color on base and card surfaces; --success at ramp step 11.

--warning-textColorReadable warning text color on base and card surfaces; defaults to --scale-yellow-11.

--info-textColorReadable informational text color on base and card surfaces; defaults to --scale-blue-11.

--inputColorForm field border color; defaults to --control-rim.

--focus-ringColorColor of the keyboard focus indicator; defaults to --ring at 70% alpha. Must clear 3:1 against every surface it lands on (WCAG 1.4.11).

--control-rimColorBoundary color of a control's own edge; defaults to --border.

--control-boundaryColorEdge of a control that has no other outline (unchecked checkbox, radio, switch track); defaults to --foreground at 60% and must clear 3:1 on --background and --card (WCAG 1.4.11).

--image-outlineColorHairline inside images and media that separates them from any surface; 10% black in light, 10% white in dark.

--control-fillColorResting fill shared by fields and surface controls; defaults to --card at 72% alpha.

--hover-fillColorWash a row or control takes on hover; defaults to a 6% tint of --foreground.

--active-fillColorWash a selected or pressed row keeps; defaults to an 8% tint of --foreground.

--canvas-grid-dotColorDot color of canvas and flow grid backgrounds.

--ring-opacityColorAlpha of the --border hairline; 0 = borderless, defaults to 1.

--scale-neutral-seedColorSeed of the neutral ramp; its hue and chroma drive --scale-neutral-1 to --scale-neutral-12.

--scale-primary-seedColorSeed of the primary ramp; its hue and chroma drive --scale-primary-1 to --scale-primary-12.

--scale-red-seedColorSeed of the red ramp; its hue and chroma drive --scale-red-1 to --scale-red-12.

--scale-orange-seedColorSeed of the orange ramp; its hue and chroma drive --scale-orange-1 to --scale-orange-12.

--scale-yellow-seedColorSeed of the yellow ramp; its hue and chroma drive --scale-yellow-1 to --scale-yellow-12.

--scale-green-seedColorSeed of the green ramp; its hue and chroma drive --scale-green-1 to --scale-green-12.

--scale-blue-seedColorSeed of the blue ramp; its hue and chroma drive --scale-blue-1 to --scale-blue-12.

--scale-purple-seedColorSeed of the purple ramp; its hue and chroma drive --scale-purple-1 to --scale-purple-12.

--scale-pink-seedColorSeed of the pink ramp; its hue and chroma drive --scale-pink-1 to --scale-pink-12.

--badge-neutralColorSoft neutral-family badge background; the skin owns the exact hue.

--badge-neutral-foregroundColorText color on the neutral-family badge.

--badge-neutral-borderColorBorder of the outline neutral-family badge variant.

--badge-neutral-hoverColorHover background of filled neutral-family badge links and buttons.

--badge-redColorSoft red-family badge background; the skin owns the exact hue.

--badge-red-foregroundColorText color on the red-family badge.

--badge-red-borderColorBorder of the outline red-family badge variant.

--badge-red-hoverColorHover background of filled red-family badge links and buttons.

--badge-orangeColorSoft orange-family badge background; the skin owns the exact hue.

--badge-orange-foregroundColorText color on the orange-family badge.

--badge-orange-borderColorBorder of the outline orange-family badge variant.

--badge-orange-hoverColorHover background of filled orange-family badge links and buttons.

--badge-yellowColorSoft yellow-family badge background; the skin owns the exact hue.

--badge-yellow-foregroundColorText color on the yellow-family badge.

--badge-yellow-borderColorBorder of the outline yellow-family badge variant.

--badge-yellow-hoverColorHover background of filled yellow-family badge links and buttons.

--badge-greenColorSoft green-family badge background; the skin owns the exact hue.

--badge-green-foregroundColorText color on the green-family badge.

--badge-green-borderColorBorder of the outline green-family badge variant.

--badge-green-hoverColorHover background of filled green-family badge links and buttons.

--badge-blueColorSoft blue-family badge background; the skin owns the exact hue.

--badge-blue-foregroundColorText color on the blue-family badge.

--badge-blue-borderColorBorder of the outline blue-family badge variant.

--badge-blue-hoverColorHover background of filled blue-family badge links and buttons.

--badge-purpleColorSoft purple-family badge background; the skin owns the exact hue.

--badge-purple-foregroundColorText color on the purple-family badge.

--badge-purple-borderColorBorder of the outline purple-family badge variant.

--badge-purple-hoverColorHover background of filled purple-family badge links and buttons.

--badge-pinkColorSoft pink-family badge background; the skin owns the exact hue.

--badge-pink-foregroundColorText color on the pink-family badge.

--badge-pink-borderColorBorder of the outline pink-family badge variant.

--badge-pink-hoverColorHover background of filled pink-family badge links and buttons.

--chart-blueColorChart series color for the blue hue; area, line, bar, arc, and legend paint read it.

--chart-purpleColorChart series color for the purple hue; area, line, bar, arc, and legend paint read it.

--chart-pinkColorChart series color for the pink hue; area, line, bar, arc, and legend paint read it.

--chart-orangeColorChart series color for the orange hue; area, line, bar, arc, and legend paint read it.

--chart-greenColorChart series color for the green hue; area, line, bar, arc, and legend paint read it.

--chart-yellowColorChart series color for the yellow hue; area, line, bar, arc, and legend paint read it.

--chart-redColorChart series color for the red hue; area, line, bar, arc, and legend paint read it.

--chart-neutralColorChart series color for the neutral hue; area, line, bar, arc, and legend paint read it.

--sidebarColorSidebar surface; defaults to --canvas.

--sidebar-foregroundColorText on the sidebar surface; defaults to --foreground.

--sidebar-primaryColorAccent of the active sidebar item; defaults to --primary.

--sidebar-accentColorHover and active wash of sidebar items; defaults to --hover-fill.

--sidebar-accent-foregroundColorText on a washed sidebar item; defaults to --foreground.

--sidebar-borderColorEdge between the sidebar and the page; defaults to --border.

--font-bodyTypographyFont ROLE for body/UI text; defaults to --font-sans.

--font-displayTypographyFont ROLE for headings; defaults to --font-sans.

--text-microTypography10px rung — kbd, badge counters, dense numeric meta.

--text-captionTypography11px rung — overlines, timestamps, group labels.

--text-labelTypography12px rung — form labels + small chrome.

--text-bodyTypography14px rung — DEFAULT body & control text.

--text-body-lgTypography16px rung — emphasized / larger body.

--text-heading-4TypographySmallest heading rung (15px).

--text-heading-4--line-heightTypographyLine-height paired onto text-heading-4.

--text-heading-4--font-weightTypographyWeight paired onto text-heading-4.

--text-heading-3TypographyHeading rung (18px).

--text-heading-3--line-heightTypographyLine-height paired onto text-heading-3.

--text-heading-3--font-weightTypographyWeight paired onto text-heading-3.

--text-heading-2TypographyHeading rung (22px).

--text-heading-2--line-heightTypographyLine-height paired onto text-heading-2.

--text-heading-2--font-weightTypographyWeight paired onto text-heading-2.

--text-heading-1TypographyLargest content heading (30px — in-page / markdown h1).

--text-heading-1--line-heightTypographyLine-height paired onto text-heading-1.

--text-heading-1--font-weightTypographyWeight paired onto text-heading-1.

--text-heading-1--letter-spacingTypographyTracking paired onto text-heading-1.

--text-displayTypographyDisplay rung above h1 (36px — page titles, heroes).

--text-display--line-heightTypographyLine-height paired onto text-display.

--text-display--font-weightTypographyWeight paired onto text-display.

--text-display--letter-spacingTypographyTracking paired onto text-display.

--radius-smRadiusScale rung: --radius × 0.6.

--radius-mdRadiusScale rung: --radius × 0.8.

--radius-lgRadiusScale rung: --radius × 1.

--radius-xlRadiusScale rung: --radius × 1.4.

--radius-2xlRadiusScale rung: --radius × 1.6.

--radius-composerRadiusComposer shell corner, concentric with the fitted control corner plus composer padding and rim.

--corner-shapeRadiusProgressive corner reshape (round | squircle | scoop | …); defaults to round.

--radius-popoverRadiusPopup container corner, concentric with the fitted row corner.

--shadow-highlightShadowInner top light painted along raised surfaces' top edge (carries its resting alpha).

--shadow-yShadowVertical bias: 0 = centered, 1 = default bottom cast.

--shadow-control-multiplierShadowElevation tier: controls; defaults to 1.

--shadow-panel-multiplierShadowElevation tier: panels; defaults to 2.

--shadow-popover-multiplierShadowElevation tier: floating popovers; defaults to 4.

--shadow-modal-multiplierShadowElevation tier: dialogs and sheets; defaults to 5.

--shadow-ambient-multiplierShadowElevation tier: ambient scene lift; defaults to 8.

--duration-loopMotionPeriod of one loader turn; essential loaders keep it under reduced motion.

--disabled-opacitySurfaceOpacity of a disabled control; defaults to 0.45.

--composer-paddingLayoutInset shared by the composer shell, toolbar controls, and nested corner geometry.

--control-h-xsLayoutDerived control height: xs (×0.78, px-snapped).

--control-h-smLayoutDerived control height: sm (×0.89, px-snapped).

--control-h-mdLayoutDerived control height: md (= --control-h).

--control-h-lgLayoutDerived control height: lg (×1.11, px-snapped).

--focus-ring-widthLayoutThickness of the keyboard focus indicator; 0 removes it and fails WCAG 2.4.7.

--focus-ring-styleLayoutLine style of the keyboard focus indicator (solid, dotted, dashed); none removes it and fails WCAG 2.4.7.

--focus-ring-offsetLayoutGap between a control edge and its focus ring; negative draws it inside. Bordered fields ignore it and paint the indicator over their border.

--control-rim-widthLayoutThickness of a control's own edge; defaults to 1px, shared across modes.

--touch-targetLayoutMinimum hit area of a control under a coarse pointer (WCAG 2.5.5); defaults to 44px.

--target-minLayoutMinimum hit area of a small control under a fine pointer (WCAG 2.5.8); defaults to 24px.

--text-input-minLayoutSmallest text-input font size under a coarse pointer, so iOS never zooms on focus; defaults to 16px.

Advanced — Color6 tokens

--successColorSuccess status color; defaults to --scale-green-9.

--warningColorWarning status color; defaults to --scale-yellow-9.

--infoColorInfo status color; defaults to --scale-blue-9.

--badge-fill-alphaColorAlpha of every tinted badge fill; defaults to 0.16.

--badge-border-alphaColorAlpha of every tinted badge border; defaults to 0.2.

--badge-hover-alphaColorAlpha a tinted badge fill reaches on hover; defaults to 0.24.

Advanced — Radius5 tokens

--radius-controlRadiusShared control corner (button, trigger, field, chip); ×2 from --radius.

--radius-fieldRadiusUser bubble corner; --radius × 2.2.

--radius-panelRadiusCode / markdown panel corner; --radius × 2.6.

--radius-sceneRadiusScene frame / large media corner; --radius × 2.8.

--radius-popup-itemRadiusSelect/menu row corner; derived from --radius-control.

Advanced — Shadow3 tokens

--shadow-colorShadowHue every shadow is tinted with.

--shadow-sizeShadowGlobal geometry multiplier: 0 = flat (the default), 1 = full depth.

--shadow-opacityShadowGlobal alpha multiplier: 1 = default density, 0 = invisible.

Advanced — Motion2 tokens

--ease-standardMotionDefault easing curve for color/text transitions.

--ease-emphasizedMotionEmphasized curve for entrances and larger moves.

Advanced — Surface5 tokens

--popover-opacitySurfaceFloating-surface translucency; <1 + blur = frosted glass.

--backdrop-blur-popoverSurfaceBackdrop blur behind floating surfaces.

--overlay-opacitySurfaceModal overlay (dialog backdrop) dim strength.

--backdrop-blur-overlaySurfaceBackdrop blur of the modal overlay.

--scroll-fade-sizeSurfaceEdge-fade depth of scrollable surfaces; 0 = hard edges.

Advanced — Layout11 tokens

--popover-paddingLayoutGap between popup container edge and rows (drives concentric corners).

--padding-xLayoutHorizontal content density of rounded surfaces (bubble, composer).

--padding-yLayoutVertical content density of rounded surfaces.

--control-hLayoutTHE base control height (md); the ramp derives from it.

--sidebar-widthLayoutExpanded sidebar width; a dragged width overrides it inline.

--sidebar-width-iconLayoutCollapsed icon-rail sidebar width.

--z-overlayLayoutStacking level of modal backdrops.

--z-modalLayoutStacking level of dialogs and sheets.

--z-popupLayoutStacking level of menus, popovers, and selects.

--z-tooltipLayoutStacking level of tooltips.

--z-toastLayoutStacking level of toasts.

The anatomy contract

Generated from canonical component DOM. Family is the selector key; slot names the part; scope identifies the component.

Copy a selector as [data-skin="brand"] [data-slot="shell"][data-control-family="chat-composer"]. Optional adornment anchors are listed separately in the machine-readable contract, one slice per paint family, so they cannot be mistaken for DOM parts.

accordion (6)

rooticonitempanelpanel-contenttrigger

action-bar (1)

root

activity (12)

rootchevroncontentcontent-griddetaildetail-contentdetail-labeliconrowstatustitletrigger

alert (3)

rootdescriptiontitle

alert-dialog (8)

backdropbodycontentdescriptionfooterheadertitletrigger

app-shell (1)

root

aspect-ratio (1)

root

audio-device-select (8)

rootcontentitempermissionpreviewstatustriggervalue

audio-recorder (9)

rootactionscancelcontentdurationstatussubmittriggervisualizer

audio-visualizer (5)

rootbarbar-trackbaselinetrack

audio-visualizer-line (1)

waveform

autocomplete (11)

rootclearcontentemptygroupgroup-labelinputitemitem-textlistpositioner

avatar (5)

rootbadgefallbackgroupimage

badge (1)

root

breadcrumb (7)

rootellipsisitemlinklistpageseparator

button (2)

rootcontent

button-group (3)

rootseparatortext

calendar (11)

rootcaption-labeldayday-cellmonthmonth-captionmonth-gridmonthsnavnav-buttonweekday

card (7)

rootactioncontentdescriptionfooterheadertitle

channel-strip (8)

rootactionsbodycontrolsheadermixertitlevalue

chart (13)

rootcenterhatch-stripehatch-tintlegendlegend-itemlegend-togglepatternsplotswatchtooltiptooltip-rowtooltip-title

chat-composer (12)

rootaccentfootermentionmention-descriptionmention-iconmention-labelshellsubmittextareatoolbartools

chat-composer-attachment (9)

rootcontentdescriptionpreviewpreview-labelprogressprogress-indicatorremovetitle

chat-composer-attachments (3)

rootlistscroll

chat-composer-editor (4)

editoreditor-rootfallbackplaceholder

chat-layout (5)

rootactionsdescriptionheadertitle

chat-message (25)

rootactionsactions-surfaceauthoravatarbodycontentedit-erroredit-inputedit-sizeredit-toolbaredit-toolbarsedit-valueeditablefooterheaderpendingreactionreaction-emojireactionsrepliesreply-summaryrowtimetyping-dots

chat-thread (4)

rootdockscroll-anchorthread-content

chat-turn (1)

turn

checkbox (2)

rootindicator

checkbox-group (2)

rootitem

code (11)

rootaccessible-sourceactionscontenteditorfloating-framegridgutterheaderlinetitle

code-diff (22)

rootaccessible-sourceactionsbodyemphasisempty-halfexpand-buttonexpanderexpander-labelfilefile-headerfile-titlegutterheaderlinemarkerrevealed-rowrowstatstat-additionsstat-deletionstitle

collapsible (3)

rootcontenttrigger

color-picker (40)

areaarea-brightnessarea-contrastarea-contrast-failarea-contrast-thresholdarea-saturationarea-thumbchannelchannel-labelchannelscontentcontrastcontrast-fixcontrast-levelcontrast-ratioeye-dropperformatinputoutputoutput-checkeroutput-coloroutput-swatchoutput-valuepanelpositionersliderslider-thumbslider-trackswatchswatch-addswatch-checkerswatch-colorswatchesswatches-groupswatches-labeltriggertrigger-checkertrigger-colorwheelwheel-thumb

combobox (13)

contentemptygroupgroup-labeliconinputinput-groupitemitem-indicatoritem-textlistpositionertrigger

command (12)

rootdialog-rootemptygroupinputinput-iconinput-wrapperitemlistloadingseparatorshortcut

context (24)

rootcontentcontent-griddescriptiongraphheaderlegendlegend-descriptionlegend-indicatorlegend-itemlegend-labellegend-valuelimit-markeroveragesegmentsummarysummary-valuetitletracktriggertrigger-indicatortrigger-labeltrigger-tracktrigger-value

context-menu (14)

checkbox-itemcontentgroupitemlabelradio-groupradio-indicatorradio-itemseparatorshortcutsub-contentsub-triggersub-trigger-indicatortrigger

dialog (8)

backdropbodycontentdescriptionfooterheadertitletrigger

dockable-panel (8)

rootactionscontentdrag-buttondrag-handledrop-zoneheadertitle

drawer (11)

backdropbodyclosecontentdescriptionfooterhandleheadertitletriggerviewport

dropdown-menu (13)

checkbox-itemcontentgroupitemlabelradio-groupradio-itemseparatorshortcutsub-contentsub-triggersub-trigger-indicatortrigger

dropzone (14)

rootareafeedbackfeedback-iconfeedback-messagefeedback-spinnerfilefile-listinputoverlayrejectionrejection-liststatustrigger

dynamic-notification (15)

rootclosecontentglassindicatorislandliquidmessagepillreplyreply-errorreply-inputreply-submittitleword

emoji-icon-picker (1)

root

emoji-picker (21)

rootcategoriescategorycategory-headercontentemojiemptyerrorfooterfooter-emojifooter-labelfooter-placeholderlistloadingrecentrecent-gridrecent-labelrowsearchsearch-iconsearch-input

empty (6)

rootcontentdescriptionheadermediatitle

field (14)

rootcontentcontroldescriptionerrorerror-reservegroupitemlabellegendseparatorseparator-contentsettitle

filter-bar (5)

rootchipexitremovesegment

flow (10)

rootcontrolsedgeedge-labeledge-label-chiphandlenodenode-bodynode-headerpanel

form (1)

root

gradient-editor (6)

rootpreviewstopstop-addtrackvalue-row

hover-card (3)

contentpositionertrigger

icon-picker (7)

rootcolorcolorscontentemptygridicon

infinite-canvas (4)

rootcontentcontrolsitem

inline-attachment (14)

rootactionactionscontentdescriptiondocumentdocument-headingdocument-linedocument-sheetdocument-stampimagemedia-imageplaceholdertitle

inline-citation (18)

rootcontentfaviconfaviconslabelnavigationnextpositionprevioussourcesource-descriptionsource-external-iconsource-faviconsource-headersource-hostnamesource-quotesource-titletrigger

input (1)

root

input-group (3)

rootaddoninput

input-otp (3)

rootseparatorslot

item (10)

rootactionscontentdescriptionfootergroupheadermediaseparatortitle

kbd (2)

rootgroup

label (1)

root

level-meter (6)

rootbarpeakscaleticktrack

live-status (1)

root

markdown (22)

rootblockquoteemphasisflowh1h2h3h4h5h6inline-codelinklist-itemordered-listparagraphseparatorstrongtabletable-celltable-headertable-scrollunordered-list

markdown-block (5)

rootcontentheadertitletitle-icon

markdown-editor (8)

rootcontentsourcetask-checkboxtask-contenttask-itemtoolbaruploads

menubar (11)

rootcontentgroupitemlabelseparatorshortcutsub-contentsub-triggersub-trigger-indicatortrigger

meter (5)

rootindicatorlabeltrackvalue

model-switcher (2)

hintvalue

morphing-panel (7)

rootbodycontentfooterheaderpositionertrigger

native-select (2)

rooticon

navigation-menu (10)

rootcontenticonitemlinklistpopuppositionertriggerviewport

number-field (7)

decrementdrag-icongroupincrementinputscrub-areascrub-cursor

page-layout (8)

rootactionsasidebodycontentdescriptionheadertitle

pagination (5)

rootcontentellipsisitemlink

phone-input (7)

rootcheckchevroncountry-codecountry-triggerflagmetadata

popover (8)

closecontentdescriptionheadertitletriggerviewportviewport-content

progress (5)

rootindicatorlabeltrackvalue

progressive-blur (2)

rootlayer

radio-group (4)

rootindicatoritemlabel

resizable (6)

floatinghandlehandle-grippanelpanel-groupsurface

resize-handle (1)

root

rich-tooltip (14)

arrowclosecontentdescriptiondotfooterheadermedianextpositionerpreviousprogresstitletrigger

scroll-area (6)

rootcontentcornerscrollbarthumbviewport

select (7)

contenticonitemitem-indicatoritem-texttriggervalue

separator (1)

root

sheet (6)

backdropclosecontentdescriptionheadertitle

sidebar (25)

rootcontainercontentcontent-stackfootergapgroupgroup-contentgroup-labelheaderinnerinsetmenumenu-actionmenu-badgemenu-buttonmenu-itemmenu-trackmobile-navmobile-nav-containermobile-triggerrailskip-linktriggerwrapper

sidebar-layout (1)

content

skeleton (1)

root

slider (9)

rootcontrolindicatorlabellabel-overlaythumbticktrackvalue

source-badge (2)

rootlabel

spinner (2)

rootindicator

stepper (9)

rootcontentdescriptionindicatoritemlistseparatortitletrigger

switch (3)

rootthumbthumb-icon

table (9)

rootbodycaptioncellcontainerfooterheadheaderrow

table-of-contents (8)

rootindicatoritemlabellistrailtracktrail

tabs (6)

rootindicatorlistpanelsurfacetab

task-list (8)

rootchevronitemitem-indicatoritemslabelprogresstrigger

textarea (1)

root

theme-toggle (3)

rootindicatoroption

thread-rail (11)

rootfilefile-iconfooteritemlinemorepopoverpopover-layersummarytitle

timeline (8)

rootcontentdescriptionindicatoritemmetaseparatortitle

toast (6)

rootcontentdescriptionindicatortitleviewport

toggle (4)

rootcheckcontentgroup

toolbar (7)

rootbuttongroupinputlinkseparatorsurface

tooltip (3)

arrowcontentpositioner

track-highlight (2)

roothover

transcript-divider (2)

rootlabel

tree (8)

rootitemitem-contentitem-groupitem-indicatoritem-labelitem-triggerlist

trigger-menu (8)

rootemptygroupgroup-labeliconitemlistpositioner

typography (2)

headingtext

user-ask (16)

rootdismissfooterfreeform-labelheaderoptionoption-descriptionoption-indicatoroption-inputoption-labelpaginationpagination-countquestionrecommendedsubmittitle

Skin requirements — the do-not list

What a pack must and must not do. Every rule is enforced by a test, so a violating pack fails the build before it ships.

contract only in theme.csstheme.css declares every contract name and nothing else; an invented var belongs in skin.css. Enforced by theme-contract-coverage.test.ts against lib/theme-contract.ts.

no @theme in a pack@theme merges globally across co-compiled packs, so a pack can never own bindings — scale intent is authored as raw scoped tokens; the @theme block belongs to Control UI core alone. Enforced per pack.

complete in both modesEvery contract token resolves in light and dark, either from one shared declaration or explicit mode declarations. A skin never inherits a missing value from Refined or core. Enforced per pack.

no component CSS in theme.css@layer components, @utility, @keyframes, and anatomy selectors live in skin.css — theme.css stays a pure token block. Enforced per pack.

skin.css never redeclares the contractA contract name re-valued in skin.css hides the change from the theme editor and this token reference; contract names are theme.css territory. Enforced per pack.

scope anatomy, never host elementsComponent selectors in skin.css key the generated [data-slot="part"][data-control-family="family"] pair, narrowed by [data-<family>-kind] when several components share a family; never skin bare host elements (code, button, input) under [data-skin]. Enforced per pack.

declared intents, mirroredcolorScheme locks the page mode to a fixed-scheme skin and motion: "reduced" collapses --duration-* through data-motion — never animation: none on finite animations. Both flags are mirrored in components/theme.ts for the pre-paint script; theme-color-scheme-lock.test.ts fails on drift.

extensions attach by anatomyA root runtime discovers interactive parts through data-control, gates its observers on the active skin, and tears down cleanly. Root runtimes stay out of skin.config and mount once in the app layout. Anchored adornment extensions are different: skin.config may import their component and render it through a typed adornment anchor while the config itself remains RSC-pure.

Adornments

JSX at named anchors — decorative chrome, or behavioral fx layers.

Additive, render zero DOM when absent, never gate library behavior. Decorative anchors (window titlebars, window controls) take plain aria-hidden JSX. Behavioral anchors (like chat-composer:send-layer) take a (ctx) => JSX render prop whose ctx carries plain render-time values — this is how a pack activates an anchored extension (send-aurora). Adornments are nested by scope and part in skin.config. Interactive values live in a separate "use client" file the pack ships, so skin.config itself stays RSC-pure.

Motion flag

One boolean, zero JavaScript.

motion: "reduced" stamps data-motion="reduced", which collapses --duration-fast/base/slow to 0 — every cva transition, Base UI enter/exit and the shimmer/ripple keyframes flatten at once. The theme editor also exposes a manual “Reduce motion” toggle.

Component knobs and the cascade

Tokens theme the whole app from :root. Knobs theme one family and live on its root element — every slot inherits.

/* app-wide: a token, on :root */

:root { --radius-field: 0.75rem; }

/* one family, everywhere: a knob, on the family root */

[data-control-family="chat-composer"] { --cui-chat-composer-shell-radius: 0; }

/* one instance, on the root element:

className="[--cui-chat-composer-shell-radius:0]" or style={{ "--cui-chat-composer-shell-radius": "0" }} */

The recipe declares each knob’s default on the family root at zero specificity, so a value set on that element always wins: style beats a skin, a skin beats the recipe, a utility class beats both. Setting a knob on :root does nothing — the family root re-declares it; re-value the token it derives from instead. Portaled surfaces are their own root: set --popup-* on the popup content, not on the trigger. Each component page lists its knobs with type and default.