An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
/* eslint-disable @typescript-eslint/no-require-imports */
/**
* @file Validates derivedVarRegistry stays in sync with component doc files,
* AND detects undocumented component CSS custom properties in source files.
*
* Three layers of checking:
* 1. Source scan: finds all component-level CSS vars in .tsx files
* 2. Doc check: verifies each var is documented in the doc file's vars[]
* 3. Registry check: verifies themeable vars have derived[] entries that
* match the registry
*
* Layers 1 and 3 each used to carry a hole that let real vars through:
*
* - The source scan skipped every `--_*` name outright, on the theory that a
* private var is "internal, not themeable". It is internal, but it is still
* documented — `theming.vars[]` takes `private: true` for exactly this
* (`--_card-radius`, `--_dropdown-menu-padding`), and the derived-var
* pipeline is what theme authors reach it through. Skipping the prefix meant
* 10 private vars across 12 (component, var) sites were declared in source
* and documented nowhere.
* - Layer 3 narrowed its verdict to vars matching `/radius|padding/`, so any
* var whose name did not happen to contain those two words was exempt from
* ever needing a derived[] mapping. That is now an explicit allowlist
* (VARS_WITHOUT_DERIVED_MAPPING) instead of a name heuristic: a new var must
* be given a derived[] entry or be added to the list on purpose.
*/
import {describe, it, expect} from 'vitest';
import {derivedVarRegistry, getDerivedVars} from './derivedVarRegistry';
import {readdirSync, readFileSync} from 'node:fs';
import {join} from 'node:path';
const SRC_DIR = join(__dirname, '..');
type ComponentDocModule = {
docs?: {
theming?: {
targets?: {className: string}[];
vars?: {name: string}[];
derived?: DerivedDocEntry[];
};
};
};
type DerivedDocEntry = {
property: string;
vars?: string[];
expand?: string;
};
// ---------------------------------------------------------------------------
// Source scanning: find CSS custom property declarations in component files
// ---------------------------------------------------------------------------
/**
* Structural/runtime vars that are NOT component-specific theming vars.
* These are set by JS at runtime or cascade through layout — they don't
* belong in derived[] because they aren't things theme authors write.
*/
const STRUCTURAL_VARS = new Set([
'--container-padding',
'--container-padding-inline',
'--container-padding-inline-start',
'--container-padding-inline-end',
'--edge-inset-start',
'--edge-inset-end',
'--container-padding-block-start',
'--container-padding-block-end',
'--container-max-height',
'--layout-padding-inner-x',
'--layout-padding-inner-y',
'--layout-padding-outer-x',
'--layout-padding-outer-y',
'--layout-padding-own-outer-x',
'--layout-padding-own-outer-y',
'--layout-content-width',
'--appshell-header-height',
'--dialog-dir-x',
'--dialog-dir-y',
'--indicator-color',
'--indicator-width',
'--table-resize-height',
'--table-resize-offset',
// sticky-columns plugin: opaque backdrop (overridable) + the row overlay it
// replays on pinned cells. Structural/runtime, not themeable design tokens.
'--table-sticky-background',
'--table-row-overlay',
// The width a cell's row divider draws (0 on the last row), which a pinned
// cell's or a detail panel's own divider reads (Table/rowDivider.ts).
// Private runtime plumbing, never authored by a theme.
'--_table-row-divider-width',
// A gliding row's divider, carried on the row for the glide
// (Table/glidingDivider.ts). Private runtime plumbing.
'--_table-row-glide-width',
'--_table-row-glide-style',
'--_table-row-glide-color',
'--_table-row-glide-offset',
'--separator-display',
'--astryx-section-padding',
// Private counterpart of the public token above: one ancestor Section's
// padding, propagated down the tree. Structural, never authored by a theme.
'--_section-padding-propagated',
// Layout's middle row tells LayoutContent that a divider-less header or
// footer sits beside it (Layout/layoutEdges.stylex.ts). Structural, never
// authored by a theme.
'--_layout-flush-block-start',
'--_layout-flush-block-end',
// ProgressBar's filled share of the track, written inline from `value` on
// every render and read by the fill's transform. Runtime state, never
// authored by a theme.
'--_progress-bar-fill',
// ProgressBar's touch layer (ProgressBarTouch) writes these inline on every
// render: the touch move's duration and curve, the three-step return offset
// and the touch minimum. The duration and curve are the progress table's
// motion roles, which no theme sets. Runtime state, never authored by a
// theme.
'--_progress-bar-move',
'--_progress-bar-curve',
'--_progress-bar-flip',
'--_progress-bar-min',
// The reduced-motion pulse's duration, curve and floor, written inline from
// the progress table on the indeterminate fill. Runtime state, never
// authored by a theme.
'--_progress-bar-pulse',
'--_progress-bar-pulse-curve',
'--_progress-bar-pulse-floor',
// The room a layer has above the software keyboard. The layer runtime
// writes it on each open layer from the keyboard's measured height
// (Layer/useLayerKeyboardClearance.ts). Runtime geometry, never authored by
// a theme.
'--_layer-keyboard-max-block-size',
// Written beside it: `auto` while the keyboard caps the layer, so the
// surface scrolls from that commit. Runtime state, never authored by a theme.
'--_layer-keyboard-overflow',
// Also beside it: how far above the viewport's bottom a layer ends while the
// keyboard is up. Runtime geometry, never authored by a theme.
'--_layer-keyboard-inset-block-end',
]);
/**
* Extract component-specific CSS custom property names from a source file.
* Matches patterns like '--_card-radius': or '--_chat-composer-padding':
* Excludes structural/runtime vars and standard token vars (--color-*,
* --spacing-*, etc.).
*
* Private (`--_*`) vars are INCLUDED. They are internal in the sense that a
* theme author does not set them directly, but they are still part of the
* documented theming surface (`theming.vars[]` with `private: true`) and are
* how derived[] entries connect a standard CSS property to a component.
*/
function extractComponentVars(filePath: string): string[] {
const content = readFileSync(filePath, 'utf-8');
const varPattern = /['"](--(\w[\w-]*))['"]\s*:/g;
const vars = new Set<string>();
let match;
while ((match = varPattern.exec(content)) !== null) {
const varName = match[1];
// Skip token vars (--color-*, --spacing-*, --radius-*, etc.)
if (
/^--(color|spacing|radius|shadow|duration|ease|transition|font|text|size)-/.test(
varName,
)
) {
continue;
}
// Skip structural vars
if (STRUCTURAL_VARS.has(varName)) {
continue;
}
// Skip vars that start with structural prefixes
if (/^--(container-|layout-|edge-|component-)/.test(varName)) {
continue;
}
vars.add(varName);
}
return [...vars];
}
// ---------------------------------------------------------------------------
// Discovery: scan all component directories
// ---------------------------------------------------------------------------
interface ComponentInfo {
dir: string;
sourceVars: string[];
docVars: string[];
docDerived: {property: string; vars?: string[]; expand?: string}[];
docTargetKeys: string[];
}
function discoverComponents(): ComponentInfo[] {
const results: ComponentInfo[] = [];
const dirs = readdirSync(SRC_DIR, {withFileTypes: true})
.filter(d => d.isDirectory())
.map(d => d.name);
for (const dir of dirs) {
const dirPath = join(SRC_DIR, dir);
const dirEntries = readdirSync(dirPath);
// Find source files with component vars (.tsx and .ts, excluding tests/docs)
const sourceFiles = dirEntries
.filter(
f =>
(f.endsWith('.tsx') || f.endsWith('.ts')) &&
!f.includes('.test.') &&
!f.endsWith('.doc.mjs') &&
!f.endsWith('.d.ts'),
)
.map(f => join(dirPath, f));
const allVars = new Set<string>();
for (const f of sourceFiles) {
for (const v of extractComponentVars(f)) {
allVars.add(v);
}
}
// Only check component directories (those with a doc file named after the
// directory). Match against the on-disk listing rather than existsSync so
// the comparison is case-exact everywhere — on case-insensitive
// filesystems (macOS, Windows) existsSync('theme/theme.doc.mjs') matches
// theme/Theme.doc.mjs and pulls in a directory that CI never checks.
if (!dirEntries.includes(`${dir}.doc.mjs`)) {
continue;
}
const docPath = join(dirPath, `${dir}.doc.mjs`);
let docVars: string[] = [];
let docDerived: DerivedDocEntry[] = [];
let docTargetKeys: string[] = [];
try {
const mod = require(docPath) as ComponentDocModule;
docVars = (mod.docs?.theming?.vars || []).map(v => v.name);
docDerived = mod.docs?.theming?.derived || [];
docTargetKeys = (mod.docs?.theming?.targets || []).map(t =>
t.className.replace(/^astryx-/, ''),
);
} catch {
/* skip */
}
// A directory earns a check by declaring a var OR by documenting a
// derived[] entry. Bailing on the var count alone (as this did) hid every
// component that is themeable purely through an expansion strategy —
// `{property: 'padding', expand: 'container'}` names no var, so such a
// component declares nothing and its registry↔doc consistency check
// silently never ran.
if (allVars.size === 0 && docDerived.length === 0) {
continue;
}
results.push({
dir,
sourceVars: [...allVars],
docVars,
docDerived,
docTargetKeys,
});
}
return results;
}
// ---------------------------------------------------------------------------
// Known mapping: doc dir → registry key
// ---------------------------------------------------------------------------
const DIR_TO_REGISTRY_KEY: Record<string, string> = {
Avatar: 'avatar',
Banner: 'banner',
BottomSheet: 'bottom-sheet',
Button: 'button',
Card: 'card',
Chat: 'chat-composer',
ContextMenu: 'context-menu',
Dialog: 'dialog',
Drawer: 'drawer',
DropdownMenu: 'dropdown-menu',
Field: 'field',
HoverCard: 'hover-card',
Icon: 'icon',
Item: 'item',
NumberInput: 'number-input',
Popover: 'popover',
ProgressBar: 'progress-bar-mark',
Section: 'section',
SegmentedControl: 'segmented-control',
TextArea: 'text-area',
};
/**
* Vars that are intentionally set by one component for use by another
* (cross-component vars). These are documented in the *consuming* component's
* doc, not the *setting* component's doc.
*
* e.g. Carousel and Thumbnail set --_button-radius for their child Buttons,
* but --_button-radius is documented in Button's doc.
*/
/**
* Private system variables a component sets that are never a theming surface:
* no component documents them, and a theme never writes them. Each is named
* by the record that requires it.
*/
const PRIVATE_SYSTEM_VARS = new Set([
// Text and Heading FR3: a container that wraps with `overflow-wrap:
// anywhere` passes it to the Text inside it; Text reads it with a
// `break-word` fallback. scripts/text-overflow-wrap-anywhere.test.mjs
// keeps every such container setting it.
'--_astryx-text-overflow-wrap',
// List FR5 and the container-padding record's corner geometry: a bleeding
// List passes its first and last rows the container corner they take.
'--_list-corner-start-start',
'--_list-corner-start-end',
'--_list-corner-end-start',
'--_list-corner-end-end',
// The container-padding record's corner geometry: a rounded Card, Dialog,
// or BottomSheet hands its block-edge radius to the shared corner
// publication beside container().
'--_container-corner-block-start',
'--_container-corner-block-end',
]);
const CROSS_COMPONENT_VARS: Record<string, string[]> = {
Carousel: ['--_button-radius'],
Thumbnail: ['--_button-radius'],
Chat: ['--_button-radius'],
// AvatarGroupOverflow sets the overlap for the Avatars it lays out; Avatar
// owns and documents it (and sets it itself when it is the group root).
AvatarGroup: ['--_avatar-group-overlap'],
// BreadcrumbItem tunes the DropdownMenu it opens.
Breadcrumbs: ['--_dropdown-menu-radius', '--_dropdown-menu-padding'],
// SelectableCard draws its selection ring through the Card shadow slot.
SelectableCard: ['--_card-ring'],
// Toolbar offsets the TabList indicator it hosts.
Toolbar: ['--_tab-indicator-bottom'],
// The destructive item variant recolors the Item it renders; Item owns,
// documents and reads both slots.
DropdownMenu: ['--_item-label-color', '--_item-description-color'],
// List's edge="flush" zeroes the inline inset of the Item each ListItem
// renders; Item owns, documents and reads it.
List: ['--_item-inset-inline'],
// A layer content root stops an outer Stepper's connector gap; Stepper owns,
// documents and reads it.
Layer: ['--step-connector-gap'],
};
/**
* Documented vars that intentionally have NO derived[] entry — a theme author
* cannot reach them by writing a standard CSS property, only by targeting the
* component's own theming surface.
*
* This replaces a `/radius|padding/` name test that exempted every var whose
* name did not contain those words. Each entry is a deliberate classification,
* so a NEW var has to be argued into the list rather than slipping past on its
* name. The list should shrink over time, not grow.
*/
const VARS_WITHOUT_DERIVED_MAPPING = new Set([
// No standard CSS property maps onto these — they are component behaviors.
'--button-focus-offset',
'--button-icon-only-aspect',
'--_avatar-group-overlap',
'--_field-status-overlap',
'--_codeblock-gutter-width',
'--_tab-indicator-bottom',
// Hit-area outset on a ::after overlay, and whether that overlay is
// generated at all — `inset` and `content` on a pseudo-element are not
// properties a theme author sets on the component.
'--_thumbnail-hit-inset',
'--_power-search-sheet-hit-inset',
// The border width a host draws where its touch hit layer reaches past,
// such as a divided ListItem's divider (0 on the last row).
// The ::after layer adds it to its offset, so the band starts past the
// border. It is the layer's geometry, not a property a theme author sets. A
// theme changes the divider through `--border-width`, which this follows.
'--_hit-border-bottom',
// The interaction overlay's colour on the ::after layer of the cards:
// written by the component's own hover and mouse `:active` arms, never a
// value a theme author sets; the overlay colours themselves are the shared
// interaction tokens.
'--_press-overlay',
// The touch press's paint at its current strength, declared once by the
// shared overlay styles on the element the controller writes to and read
// by whatever paints it. A theme sets `--color-overlay-pressed`, not this.
'--_press-paint',
'--_press-paint-image',
// A checkbox row's touch press image, which an indicator that paints its
// own press inherits. The row writes it from the press paint above.
'--_indicator-press-image',
// A CheckboxList row's own press paint, handed to its checkbox's box:
// written by the row's own press arms, never a value a theme author sets.
'--_checkbox-row-press-paint',
'--_power-search-sheet-hit-content',
// Placement and swipe lifecycle values are private Toast behavior. A theme
// author controls the surface transform/opacity as a whole, not these values.
'--_toast-slide-y',
'--_toast-swipe-y',
'--_toast-swipe-exit-y',
'--_toast-swipe-opacity',
'--_toast-swipe-scale',
// Set by each ChatMessage article from its own content and read as its
// avatar's top margin, so the avatar lines up with a name row. Content
// state, not a value a theme author sets.
'--_chat-avatar-offset',
// Indentation and row-spacing metrics: --tree-list-indent is the authorable
// step, --_tree-indent the per-row distance TreeListItem computes from it.
// --tree-list-row-gap is applied as half a padding-block on each row wrapper,
// not as gap on the list, so no standard property on the tree-list target
// maps onto it; a theme sets the var directly.
'--tree-list-indent',
'--_tree-indent',
'--tree-list-row-gap',
// Published by each treeitem while it has keyboard focus and read as its
// row's z-index, so the focused row paints above the guide lines. Focus
// state, not a value a theme author sets.
'--_tree-focus-z',
// Clipped on the ONE side each on-track connector segment faces the
// indicator from — trailing above the node, leading below it, mirrored
// again per axis. No standard property maps onto this purpose-based seam:
// one clip must cover the segment and its pseudo-element fill together.
'--step-connector-gap',
// Composed into a single box-shadow list on the card, so neither maps 1:1
// onto boxShadow — setting one through a derived entry would clobber the
// other.
'--_card-elevation',
'--_card-ring',
// The colour inside that composed ring, for a variant only a theme knows.
// It is one component of one shadow in the list, so no standard property
// maps onto it either — a theme sets it beside the fill it has to contrast.
'--selectable-card-ring-color',
// The spinner's ring is drawn as an SVG circle, so none of its five vars is
// a CSS property of the element carrying the theme target: `width` and
// `borderWidth` would name a box the ring is not, a `color` mapping would
// take the label's text color with it, and the arc fraction is a pure
// dash-length multiplier with no standard property to attach to. They are
// public vars a theme sets directly under a size- or shade-variant key.
'--spinner-diameter',
'--spinner-stroke-width',
'--spinner-color',
'--spinner-track-color',
'--spinner-arc-fraction',
// Set by a PARENT component (e.g. the destructive dropdown/context menu
// item) to recolor the two text lines it renders. A single standard `color`
// property cannot map onto both lines, and the root color is not what they
// control — a theme reaches them by setting the vars directly.
'--_item-label-color',
'--_item-description-color',
]);
// ---------------------------------------------------------------------------
// Tests
// ---------------------------------------------------------------------------
describe('component CSS vars are documented and themeable', () => {
const components = discoverComponents();
for (const {dir, sourceVars, docVars, docDerived} of components) {
const crossVars = new Set(CROSS_COMPONENT_VARS[dir] || []);
it(`${dir}: all source vars are in doc file`, () => {
const undocumented = sourceVars.filter(
v =>
!docVars.includes(v) &&
!crossVars.has(v) &&
!PRIVATE_SYSTEM_VARS.has(v),
);
expect(
undocumented,
`${dir} has undocumented CSS vars in source: ${undocumented.join(', ')}. ` +
`Add them to ${dir}.doc.mjs theming.vars[] and add a derived[] ` +
`entry mapping the standard CSS property to the internal var.`,
).toEqual([]);
});
it(`${dir}: documented vars have derived entries for theming`, () => {
// Every var that maps to a standard CSS property should have a
// derived entry so theme authors can write standard CSS.
const derivedVarNames = new Set(docDerived.flatMap(d => d.vars || []));
const derivedExpands = docDerived
.filter(d => d.expand)
.map(d => d.expand);
const hasContainerExpand = derivedExpands.includes('container');
const missingDerived = docVars.filter(varName => {
// Cross-component vars are handled by the owning component
if (crossVars.has(varName)) {
return false;
}
// Check if this var is covered by a derived entry
if (derivedVarNames.has(varName)) {
return false;
}
// Container expansion covers padding-related vars
if (hasContainerExpand && varName.includes('padding')) {
return false;
}
return true;
});
// Everything that is not explicitly classified as unmappable must have
// a derived[] entry. (This was a `/radius|padding/` name test, which
// exempted any var whose name lacked those words.)
const themeableVars = missingDerived.filter(
v => !VARS_WITHOUT_DERIVED_MAPPING.has(v),
);
expect(
themeableVars,
`${dir} has vars that should be themeable via derived[]: ${themeableVars.join(', ')}. ` +
`Add derived[] entries in ${dir}.doc.mjs mapping standard CSS ` +
`properties (borderRadius, padding) to these internal vars — or, if ` +
`no standard property maps onto them, add them to ` +
`VARS_WITHOUT_DERIVED_MAPPING with the reason.`,
).toEqual([]);
});
}
});
describe('derivedVarRegistry ↔ doc file consistency', () => {
const components = discoverComponents();
for (const {dir, docDerived, docTargetKeys} of components) {
const key = DIR_TO_REGISTRY_KEY[dir];
if (!key || docDerived.length === 0) {
continue;
}
it(`${dir} (${key}): registry matches doc derived`, () => {
const registryEntries = derivedVarRegistry[key];
expect(registryEntries).toBeDefined();
expect(registryEntries).toEqual(docDerived);
});
// generateThemeRules looks the registry up by the theme's components key,
// so a key that is not one of the doc's targets never expands.
it(`${dir} (${key}): registry key is a documented theming target`, () => {
expect(docTargetKeys).toContain(key);
});
}
// Catch new doc files with derived that have no registry key mapping
it('every doc with theming.derived has a registry mapping', () => {
const missing: string[] = [];
for (const {dir, docDerived} of components) {
if (docDerived.length === 0) {
continue;
}
const key = DIR_TO_REGISTRY_KEY[dir];
if (!key) {
missing.push(
`${dir}: has theming.derived but no DIR_TO_REGISTRY_KEY mapping. ` +
`Add the mapping and a derivedVarRegistry entry.`,
);
} else if (!derivedVarRegistry[key]) {
missing.push(
`${dir} (${key}): has theming.derived but no derivedVarRegistry entry.`,
);
}
}
expect(missing).toEqual([]);
});
it('registry has no orphan entries', () => {
const validKeys = new Set(Object.values(DIR_TO_REGISTRY_KEY));
const orphans = Object.keys(derivedVarRegistry).filter(
k => !validKeys.has(k),
);
expect(orphans).toEqual([]);
});
});
describe('getDerivedVars', () => {
it('returns matching entries for card borderRadius', () => {
const result = getDerivedVars('card', 'borderRadius');
expect(result).toHaveLength(1);
expect(result[0].vars).toEqual(['--_card-radius']);
});
it('returns empty for unknown component', () => {
expect(getDerivedVars('unknown', 'borderRadius')).toEqual([]);
});
it('does not resolve removed target aliases', () => {
expect(getDerivedVars('hovercard', 'borderRadius')).toEqual([]);
expect(getDerivedVars('textarea', 'paddingInline')).toEqual([]);
expect(getDerivedVars('progressbar-mark', 'width')).toEqual([]);
});
it('returns empty for unregistered property', () => {
expect(getDerivedVars('card', 'color')).toEqual([]);
});
it('marks text-area paddingInline as replacing the source property', () => {
const result = getDerivedVars('text-area', 'paddingInline');
expect(result).toHaveLength(1);
expect(result[0].vars).toEqual(['--_textarea-inline-padding']);
expect(result[0].replaces).toBe(true);
});
it('marks icon width and height as replacing the source property', () => {
// spec:AST-087 FR10: the glyph reads these vars for its dimension, so a
// raw width/height beside them would only compete with its size styles.
for (const [property, varName] of [
['width', '--_icon-width'],
['height', '--_icon-height'],
]) {
const result = getDerivedVars('icon', property);
expect(result).toHaveLength(1);
expect(result[0].vars).toEqual([varName]);
expect(result[0].replaces).toBe(true);
}
});
it('marks progress-bar-mark width and height as replacing the source property', () => {
for (const [property, varName] of [
['width', '--_progressbar-mark-width'],
['height', '--_progressbar-mark-height'],
]) {
const result = getDerivedVars('progress-bar-mark', property);
expect(result).toHaveLength(1);
expect(result[0].vars).toEqual([varName]);
expect(result[0].replaces).toBe(true);
}
});
});
// ---------------------------------------------------------------------------
// Read check: a registered var nothing reads is a dead theming knob
// ---------------------------------------------------------------------------
/**
* Every source file under packages/core/src, concatenated once.
*
* `--_popover-radius` shipped documented and registered while `usePopover`
* hardcoded its radius, so `popover: {borderRadius}` set a var no element ever
* read. Sync between source, docs and registry cannot catch that: the three
* agreed with each other, and none of them required a reader.
*/
function readAllSource(dir: string): string {
let out = '';
for (const entry of readdirSync(dir, {withFileTypes: true})) {
const path = join(dir, entry.name);
if (entry.isDirectory()) {
out += readAllSource(path);
} else if (
(entry.name.endsWith('.ts') || entry.name.endsWith('.tsx')) &&
!entry.name.includes('.test.') &&
!entry.name.endsWith('.d.ts')
) {
out += readFileSync(path, 'utf-8');
}
}
return out;
}
describe('registered derived vars are read by component styles', () => {
const source = readAllSource(SRC_DIR);
for (const [component, entries] of Object.entries(derivedVarRegistry)) {
for (const varName of entries.flatMap(e => e.vars ?? [])) {
it(`${component}: ${varName} is read via var()`, () => {
expect(
source.includes(`var(${varName})`) ||
source.includes(`var(${varName},`),
`${varName} is registered as the derived var for a CSS property on ` +
`\`${component}\`, but no component reads it. A theme setting that ` +
`property would write a var nothing consumes. Read it in the ` +
`element's StyleX styles, or drop the derived entry.`,
).toBe(true);
});
}
}
});