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 26 tokens a skin typically re-values first

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

--foregroundColorDefault text color on --background.

--cardColorElevated card surface.

--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).

--inputColorForm field border color.

--ringColorFocus ring color.

--canvasColorThe page paper the scene/panels float on — a level BELOW --background.

--font-sansTypographyTypeface for the whole UI.

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

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

--duration-fastMotionFast tempo (hover, color).

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

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

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

--primary-textColorReadable brand text color on base and card surfaces.

--destructive-textColorReadable destructive text color on base and card surfaces.

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

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

--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.

--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-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.

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

--corner-radius-fitRadiusFallback radius shrink where corner-shape: squircle is unsupported.

--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.

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

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

--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 indicator; negative draws the indicator inside.

Advanced — Typography1 token

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

Advanced — Radius5 tokens

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

--radius-fieldRadiusUser bubble / composer shell 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: 1 = default depth, 0 = flat.

--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 — Layout4 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.

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 full machine-readable contract, so they cannot be mistaken for DOM parts.

accordion (5)

rooticonitempaneltrigger

action-bar (1)

root

activity (13)

rootannouncementchevroncontentcontent-viewportdetaildetail-contentdetail-labeliconrowstatustitletrigger

alert (3)

rootdescriptiontitle

alert-dialog (7)

backdropcontentdescriptionfooterheadertitletrigger

aspect-ratio (1)

root

audio-recorder (9)

rootactionscancelcontentdurationstatussubmittriggervisualizer

audio-visualizer (5)

rootbarbar-trackbaselinetrack

audio-visualizer-line (1)

waveform

autocomplete (10)

rootclearcontentemptygroupgroup-labelinputitemlistpositioner

avatar (4)

rootfallbackgroupimage

badge (1)

root

breadcrumb (7)

rootellipsisitemlinklistpageseparator

button (2)

rootcontent

button-group (3)

rootseparatortext

calendar (11)

rootcaption-labeldayday-cellmonthmonth-captionmonth-gridmonthsnavnav-buttonweekday

card (7)

rootactioncontentdescriptionfooterheadertitle

chat-composer (12)

rootaccentfootermentionmention-descriptionmention-iconmention-labelshellsubmittextareatoolbartools

chat-composer-attachment (10)

rootcontentdescriptionpreviewpreview-labelprogressprogress-indicatorremovestatustitle

chat-composer-attachments (3)

rootlistscroll

chat-composer-editor (4)

rooteditorfallbackplaceholder

chat-layout (1)

root

chat-message (7)

rootactionsavatarbodycontentheaderrow

chat-thought (5)

rootchevrondetailstitletrigger

chat-thread (1)

root

chat-turn (1)

turn

checkbox (2)

rootindicator

checkbox-group (1)

root

code (9)

rootaccessible-sourceactionscontentgridgutterheaderlinetitle

code-block-editor (6)

rootactionscontenteditorheadertitle

code-diff (21)

rootaccessible-sourceactionsbodyemphasisempty-halfexpand-buttonexpanderexpander-labelfilefile-headerfile-titlegutterheaderlinemarkerrowstatstat-additionsstat-deletionstitle

collapsible (3)

rootcontenttrigger

color-picker (40)

alphaalpha-thumbalpha-trackareaarea-brightnessarea-saturationarea-thumbchannelchannel-labelchannelscontentcontrastcontrast-fixcontrast-levelcontrast-ratioeye-dropperformathuehue-thumbhue-trackinputoutputoutput-checkeroutput-coloroutput-swatchoutput-valuepanelpositionerswatchswatch-addswatch-checkerswatch-colorswatchesswatches-groupswatches-labeltriggertrigger-checkertrigger-colorwheelwheel-thumb

combobox (12)

rootcontentemptygroupgroup-labeliconinputitemitem-indicatorlistpositionertrigger

command (11)

rootdialog-rootemptygroupinputinput-iconinput-wrapperitemlistseparatorshortcut

context (23)

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

context-menu (14)

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

dialog (7)

backdropcontentdescriptionfooterheadertitletrigger

dockable-panel (7)

rootactionscontentdrag-handledrop-zoneheadertitle

drawer (10)

backdropclosecontentdescriptionfooterhandleheadertitletriggerviewport

dropdown-menu (5)

contentitemlabelseparatortrigger

dropzone (14)

rootareafeedbackfeedback-iconfeedback-messagefeedback-spinnerfilefile-listinputoverlayrejectionrejection-liststatustrigger

dynamic-notification (14)

rootclosecontentglassindicatorislandliquidmessagepillreplyreply-inputreply-submittitleword

empty (6)

rootcontentdescriptionheadermediatitle

environment-variables (22)

rootactionscolumn-labelsdescriptionemptyfield-errorfield-labelheaderhinthint-codekey-inputmessagereadonly-itemreadonly-keyreadonly-listreadonly-valuerowrowstitletoolbarvalue-groupvalue-input

field (13)

rootcontentcontroldescriptionerrorgroupitemlabellegendseparatorseparator-contentsettitle

form (1)

root

gradient-editor (5)

rootpreviewstopstop-addtrack

hover-card (3)

contentpositionertrigger

infinite-canvas (3)

rootcontentcontrols

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

markdown (18)

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

markdown-block (5)

rootcontentheadertitletitle-icon

menubar (11)

rootcontentgroupitemlabelseparatorshortcutsub-contentsub-triggersub-trigger-indicatortrigger

meter (5)

rootindicatorlabeltrackvalue

model-switcher (4)

roothintindicatorvalue

morphing-panel (3)

rootcontenttrigger

native-select (2)

rooticon

navigation-menu (10)

rootcontenticonitemlinklistpopuppositionertriggerviewport

number-field (7)

decrementdrag-icongroupincrementinputscrub-areascrub-cursor

pagination (5)

rootcontentellipsisitemlink

phone-input (6)

checkchevroncountry-codecountry-triggerflagmetadata

popover (6)

closecontentdescriptionheadertitletrigger

progress (5)

rootindicatorlabeltrackvalue

radio-group (3)

rootindicatoritem

resizable (4)

handlehandle-grippanelpanel-group

rich-tooltip (14)

arrowclosecontentdescriptiondotfooterheadermedianextpositionerpreviousprogresstitletrigger

scroll-area (6)

rootcontentcornerscrollbarthumbviewport

select (5)

contenticonitemitem-indicatortrigger

separator (1)

root

sheet (6)

backdropclosecontentdescriptionheadertitle

sidebar (17)

rootcontainercontentfootergapgroupgroup-labelheaderinnerinsetmenumenu-buttonmenu-itemmenu-trackrailtriggerwrapper

sidebar-layout (1)

content

skeleton (1)

root

slider (8)

rootcontrolindicatorlabelthumbticktrackvalue

source-badge (2)

rootlabel

spinner (2)

rootindicator

stepper (9)

rootcontentdescriptionindicatoritemlistseparatortitletrigger

switch (3)

rootthumbthumb-icon

table (9)

rootbodycaptioncellcontainerfooterheadheaderrow

table-of-contents (7)

rootitemlabellistrailtracktrail

tabs (5)

rootindicatorlistpaneltab

task-list (8)

rootchevronitemitem-indicatoritemslabelprogresstrigger

textarea (1)

root

thread-rail (11)

rootfilefile-iconfooteritemlinemorepopoverpopover-layersummarytitle

timeline (8)

rootcontentdescriptionindicatoritemmetaseparatortitle

toast (8)

rootactionclosecontentdescriptionindicatortitleviewport

toggle (4)

rootcheckcontentgroup

toolbar (6)

rootbuttongroupinputlinkseparator

tooltip (4)

arrowarrow-shapecontentpositioner

track-highlight (2)

roothover

transcript-divider (2)

rootlabel

tree (8)

rootitemitem-contentitem-groupitem-indicatoritem-labelitem-triggertrack

trigger-menu (8)

rootemptygroupgroup-labeliconitemlistpositioner

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.

css

/* 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.

Skins

Each pack's tokens, skin.css and config, ready to read and install.

RefinedCompact, calm starting skin with a complete Control UI token contract.Theme Windows XPWindows XP-inspired Luna tokens, bevels, and titlebar details.Advanced Liquid metalPolished metal skin with a WebGL shader control surface.Advanced RigBrutalist skin with coral accents, squared corners, and dense typography.Theme FlatNeutral reset skin with square corners, no shadows, and the stock motion tempo.Theme Modern AppleApple-inspired Liquid Glass skin: WebGL-refraction on floating surfaces, precise directional rims, transparent inputs, and continuous corners.Advanced CuicuiCuicui-inspired shell skin with fixed grain, a docked w-80 sidebar, a neutral main container, and the send-aurora anchored extension on ChatComposer (skin.config fills the chat-composer:send-layer anchor).Advanced LinearLinear-inspired skin: indigo brand on a cool neutral ramp, a flat 13px chrome band, 4px radius, hairline borders instead of elevation, and pill-shaped filled actions.Advanced