@prongsjs/ui 0.0.0-stage → 0.2.0

package/dist/tooling/spec.js

@@ -0,0 +1,360 @@
+import { COMPONENT_NAMES, componentFor } from '../vocabulary.js';
+import { COMPONENT_DOCS, LAYOUT_PROPS } from './components.js';
+import { SURFACE_TOKENS, THEME_TOKENS } from './theme.js';
+/** What an intent renders, without its classes: `<form>`, `role="status"`, `type="email"`. */
+export function describeBinding(binding) {
+    const b = binding;
+    const parts = [];
+    if (b.element)
+        parts.push(`<${b.element}>`);
+    if (b.ariaRole)
+        parts.push(`role="${b.ariaRole}"`);
+    if (b.behavior?.type)
+        parts.push(`type="${b.behavior.type}"`);
+    if (b.behavior?.role)
+        parts.push(`role="${b.behavior.role}"`);
+    const arrangement = arrangementOf(b.classes ?? '');
+    return [...parts.map((p) => '`' + p + '`'), arrangement && `(${arrangement})`].filter(Boolean).join(' ');
+}
+/**
+ * How a box already lays out its children, read from its classes: `column, gap-4, centred
+ * max-w-2xl`. Agents read this instead of the registry to know what not to repeat in className.
+ */
+function arrangementOf(classes) {
+    const list = classes.split(/\s+/);
+    const has = (name) => list.includes(name);
+    const flow = has('grid') ? 'grid' : has('flex-col') ? 'column' : has('flex-row') || has('flex') ? 'row' : '';
+    if (!flow)
+        return '';
+    const gap = list.find((name) => /^gap-[\d.]+$/.test(name));
+    const width = has('mx-auto') ? list.find((name) => name.startsWith('max-w-')) : undefined;
+    return [flow, gap, width && `centred ${width}`].filter(Boolean).join(', ');
+}
+const NESTING = [
+    { ids: ['layout.form', 'layout.field', 'layout.actions'], text: '`layout.form` holds `layout.field`s, then one `layout.actions` with its buttons.' },
+    {
+        ids: ['layout.field', 'text.label', 'text.caption', 'feedback.error'],
+        text: '`<Field label hint error>` renders a `layout.field`: its `text.label`, the field, a `text.caption` hint and a `feedback.error`, with the ids that connect them. Build a `layout.field` by hand only for something Field cannot render, and connect the ids yourself.',
+    },
+    { ids: ['layout.list', 'layout.item'], text: '`layout.list` (`<ul>`) holds only `layout.item`s (`<li>`). Put anything else inside the items.' },
+    {
+        ids: ['layout.table'],
+        text: '`layout.table` is the `<table>`. Inside it write plain `<thead>`, `<tbody>`, `<tr>`, `<th scope="col">` and `<td>` with no classes; put `<Text>` and `<Action>` intents in the cells. When it has more columns than fit on a phone, wrap it in `<Layout intent="layout.scroller" tabIndex={0} aria-label="...">`.',
+    },
+    { ids: ['layout.shell', 'layout.aside', 'layout.page'], text: '`layout.shell` holds one `layout.aside` (the sidebar) and the `layout.page`.' },
+    { ids: ['layout.meta', 'text.meta'], text: '`layout.meta` holds `text.meta` facts (time, author, counts) about one item.' },
+    { ids: ['layout.toolbar'], text: '`layout.toolbar` holds the controls for the content below it: filters, views, search, a refresh.' },
+    { ids: ['layout.notice', 'action.dismiss'], text: '`layout.notice` holds one `feedback.*` message and an `action.dismiss`.' },
+    { ids: ['layout.disclosure', 'text.summary'], text: '`layout.disclosure` (`<details>`) starts with one `text.summary` line, then the content it opens.' },
+    { ids: ['layout.divider', 'layout.list'], text: '`layout.divider` is an `<hr>` between parts of the same content. Lines between list items come from `layout.list`.' },
+    { ids: ['popover.menu'], text: 'A `<Popover>` takes the `<Action>` that opens it as `trigger`. A `popover.menu` holds `<Action>`s, which look like menu items inside it.' },
+    { ids: ['dialog.confirm', 'layout.actions'], text: 'A `<Dialog>` holds a heading, its content and a `layout.actions` row. Set its `label` to the heading text.' },
+];
+const EXAMPLES = [
+    {
+        title: 'A form with a label, a hint and an error',
+        ids: ['layout.form', 'layout.field', 'text.label', 'field.text', 'feedback.error', 'field.email', 'text.caption', 'layout.actions', 'action.cancel', 'action.save'],
+        text: `<Layout intent="layout.form" onSubmit={save}>
+  <Field intent="field.text" label="Display name" error={nameError} value={name} onChange={(e) => setName(e.target.value)} />
+  <Field intent="field.email" label="Email" hint="Only used for signing in." />
+  <Layout intent="layout.actions">
+    <Action intent="action.cancel" onClick={cancel}>Cancel</Action>
+    <Action intent="action.save" type="submit">Save</Action>
+  </Layout>
+</Layout>`,
+    },
+    {
+        title: 'A list of items with facts and a row action',
+        ids: ['layout.list', 'layout.item', 'media.person', 'layout.group', 'heading.item', 'layout.meta', 'text.meta', 'action.remove'],
+        text: `<Layout intent="layout.list">
+  {members.map((member) => (
+    <Layout key={member.id} intent="layout.item" className="flex-row items-center">
+      <Media intent="media.person" src={member.avatarUrl} alt={member.name} />
+      <Layout intent="layout.group" className="flex-1">
+        <Text intent="heading.item">{member.name}</Text>
+        <Layout intent="layout.meta">
+          <Text intent="text.meta">{member.role}</Text>
+          <Text intent="text.meta">Joined {member.joined}</Text>
+        </Layout>
+      </Layout>
+      <Action intent="action.remove" onClick={() => remove(member.id)}>Remove</Action>
+    </Layout>
+  ))}
+</Layout>`,
+    },
+    {
+        title: 'A toolbar with filters, views and search',
+        ids: ['layout.toolbar', 'choice.filter', 'nav.view', 'field.search'],
+        text: `<Layout intent="layout.toolbar">
+  {['All', 'Unread', 'Starred'].map((name) => (
+    <Action key={name} intent="choice.filter" pressed={filter === name} onClick={() => setFilter(name)}>{name}</Action>
+  ))}
+  <Action intent="nav.view" pressed={view === 'list'} onClick={() => setView('list')}>List</Action>
+  <Action intent="nav.view" pressed={view === 'grid'} onClick={() => setView('grid')}>Grid</Action>
+  <Field intent="field.search" aria-label="Search articles" value={query} onChange={(e) => setQuery(e.target.value)} />
+</Layout>`,
+    },
+    {
+        title: 'A confirmation dialog',
+        ids: ['action.delete', 'dialog.confirm', 'layout.group', 'heading.item', 'text.body', 'layout.actions', 'action.cancel'],
+        text: `<Action intent="action.delete" onClick={() => setOpen(true)}>Delete project</Action>
+<Dialog intent="dialog.confirm" open={open} onClose={() => setOpen(false)} label="Delete this project?">
+  <Layout intent="layout.group" className="gap-4">
+    <Text intent="heading.item" as="h2">Delete this project?</Text>
+    <Text intent="text.body">The project and all its data will be gone for good.</Text>
+    <Layout intent="layout.actions">
+      <Action intent="action.cancel" onClick={() => setOpen(false)}>Cancel</Action>
+      <Action intent="action.delete" onClick={deleteProject}>Delete</Action>
+    </Layout>
+  </Layout>
+</Dialog>`,
+    },
+    {
+        title: 'Loading, empty and a dismissible notice',
+        ids: ['layout.loading', 'layout.group', 'text.body', 'action.create', 'layout.notice', 'feedback.success', 'action.dismiss'],
+        text: `{projects === undefined && <Layout intent="layout.loading" className="h-24" aria-busy="true" />}
+{projects?.length === 0 && (
+  <Layout intent="layout.group">
+    <Text intent="text.body">No projects yet.</Text>
+    <Action intent="action.create" href="/projects/new">Create your first project</Action>
+  </Layout>
+)}
+{saved && (
+  <Layout intent="layout.notice">
+    <Text intent="feedback.success">Your changes were saved.</Text>
+    <Action intent="action.dismiss" icon={<CloseIcon />} label="Dismiss" onClick={() => setSaved(false)} />
+  </Layout>
+)}`,
+    },
+];
+/** The props section of PRONGS.md, from COMPONENT_DOCS. `intent` and `unsafeClassName` are covered by the rules above. */
+function componentProps() {
+    const withLayout = COMPONENT_NAMES.filter((name) => COMPONENT_DOCS[name].layoutProps).map((name) => `\`<${name}>\``);
+    const out = [
+        'Each component also takes its element’s usual attributes (`id`, `onClick`, `aria-*`, `data-*`...), except `className` and `style`.',
+        '',
+        `Layout props, on ${withLayout.slice(0, -1).join(', ')} and ${withLayout.at(-1)}: ${LAYOUT_PROPS.map((p) => `\`${p.name}\` (${p.type})`).join(', ')}.`,
+    ];
+    for (const name of COMPONENT_NAMES) {
+        const doc = COMPONENT_DOCS[name];
+        out.push('', `### \`<${name}>\` props`, '');
+        for (const prop of doc.props) {
+            // intent and unsafeClassName are in the rules above; ref works as it does on any element.
+            if (prop.name === 'intent' || prop.name === 'unsafeClassName' || prop.name === 'ref')
+                continue;
+            out.push(`- \`${prop.name}\`${prop.required ? ' (required)' : ''}: ${prop.description}`);
+        }
+        out.push(...doc.rules.map((rule) => `- Rule: ${rule}`));
+    }
+    return out;
+}
+/** The examples whose intents all exist, for tests that check them against a registry. */
+export function specExamples(registry) {
+    return EXAMPLES.filter((e) => e.ids.every((id) => registry.has(id))).map((e) => ({ title: e.title, code: e.text }));
+}
+export function uiSpecSection(registry, context) {
+    const from = context.componentsImport ?? './components/prongs';
+    const has = (g) => g.ids.every((id) => registry.has(id));
+    const out = [
+        '## UI rules',
+        '',
+        `\`import { ${COMPONENT_NAMES.join(', ')} } from '${from}';\``,
+        '',
+        '- The intent decides the element (`heading.page` renders `<h1>`). Use `as` on `<Text>` only to fix document structure.',
+        `- ${COMPONENT_NAMES.filter((n) => n !== 'Layout').map((n) => `\`<${n}>\``).join(', ')} take no \`className\` or \`style\`. Spacing comes from the parent \`<Layout>\`.`,
+        '- `<Layout>` takes a `className` for layout and spacing only (margins, sizes, flex/grid, gaps, padding, text alignment).',
+        '- `unsafeClassName` bypasses the intent. It needs a `// prongs-unsafe: <reason>` comment on the line above and is counted by `check`.',
+        '- Do not use raw `<button>`, `<h1>`–`<h6>`, `<input>`, `<textarea>`, `<select>`, `<dialog>`, or styled `<p>`/`<span>`/`<a>`/`<div>`. A justified exception takes `// prongs-ignore: <reason>` on the line above.',
+        '- State is a prop, not a style: `pressed` for toggles, choices and views (sets `aria-pressed`), `current` for the page or step you are on (sets `aria-current`). Other state goes in `data-*` attributes (`data-read`, `data-compact`), which `<Text>`, `<Action>`, `<Field>`, `<Layout>` and `<Media>` pass to their element; the intent styles them with `data-[read]:` variants. Never switch classes or intents to show state.',
+        "- Values that come from data (a colour the user picked) go through `vars={{ '--name': value }}`, never `style`.",
+        '- Every element carries `data-intent` (e.g. `data-intent="action.delete"`) for analytics, tests and A/B tools to find it by purpose. Never style with it, in CSS or in classes: looks come from the registry.',
+        '- Inline emphasis inside a sentence is plain `<strong>` or `<em>`, not an intent. Thematic breaks are `<hr>`.',
+        '',
+        '## Component props',
+        '',
+        ...componentProps(),
+    ];
+    const nesting = NESTING.filter(has);
+    if (nesting.length)
+        out.push('', '## How intents nest', '', ...nesting.map((n) => `- ${n.text}`));
+    const examples = EXAMPLES.filter(has);
+    if (examples.length) {
+        out.push('', '## Examples', '');
+        for (const e of examples)
+            out.push(`### ${e.title}`, '', '```tsx', e.text, '```', '');
+    }
+    return out.join('\n');
+}
+/** What only editing the registry or the theme needs: PRONGS.reference.md. */
+export function uiReferenceSection() {
+    return themeSection().join('\n');
+}
+/** How the registry's classes reach colours: for whoever edits the registry. */
+function themeSection() {
+    const colors = THEME_TOKENS.filter((t) => t.utility).map((t) => '`' + t.utility + '`');
+    const surface = SURFACE_TOKENS.map((t) => `- \`${t.utility}\` (\`var(${t.name})\`): ${t.description}`);
+    return [
+        '## Theme',
+        '',
+        'The registry is the only place classes live, and its colours come from the theme (`theme.css`), never from values. `prongs check` reports a colour literal or a Tailwind palette colour in the registry (`raw-value`), and a `var()` that nothing declares (`unknown-token`).',
+        '',
+        `Colours, as Tailwind colours (\`bg-primary\`, \`text-success\`): ${colors.join(', ')}.`,
+        '',
+        'Surfaces layer themselves. A look with the class `surface` sits one level above the surface it is in; `surface-inset` is a recess, `surface-overlay` floats over the page (dialogs, menus), and `surface-page` restarts at level 0 under an element that sets its own `--background`/`--foreground`. Inside one, use the surface colours (`hover:bg-surface-hover`, `text-surface-muted`, `border-surface-border`) so hover fills, quiet text and hairlines stay visible at every level:',
+        '',
+        ...surface,
+    ];
+}
+/** How a call site writes an intent, for `prongs find`. */
+export function uiUsage(id, binding) {
+    const component = componentFor(id);
+    const b = binding;
+    if (component === 'Field')
+        return `<Field intent="${id}" label="…" />`;
+    if (component === 'Layout' && b.element === 'hr')
+        return `<Layout intent="${id}" />`;
+    if (component === 'Dialog')
+        return `<Dialog intent="${id}" open={open} onClose={close} label="…">…</Dialog>`;
+    if (component === 'Popover')
+        return `<Popover intent="${id}" label="…" trigger={<Action intent="…">…</Action>}>…</Popover>`;
+    return `<${component} intent="${id}">…</${component}>`;
+}
+/** Groups the spec's index by the component that renders each intent. */
+export function groupByComponent(id) {
+    const component = componentFor(id);
+    return component ? `\`<${component}>\`` : `\`${id.split('.')[0]}\``;
+}
+/**
+ * What the UI profile adds to PRONGS.md, without the code analysis (and the TypeScript
+ * compiler it needs). For writing the spec somewhere other than the CLI, like a docs site.
+ */
+export { COMPONENT_DOCS, LAYOUT_PROPS } from './components.js';
+export const uiSpecTooling = {
+    name: 'ui',
+    describe: describeBinding,
+    groupOf: groupByComponent,
+    usage: uiUsage,
+    specSection: uiSpecSection,
+    referenceSection: uiReferenceSection,
+};
+/** What each UI rule finds, for the docs and for anyone reading a check report. */
+export const UI_RULE_DOCS = [
+    {
+        id: 'raw-element',
+        profile: 'ui',
+        severity: 'error',
+        summary: 'A `<button>`, `<h2>`, `<input>` or styled `<p>`/`<span>`/`<a>` instead of a component. Suggests the closest intents.',
+        bad: '<button className="rounded bg-red-600 px-4 text-white" onClick={remove}>Delete</button>',
+        good: '<Action intent="action.delete" onClick={remove}>Delete</Action>',
+    },
+    {
+        id: 'raw-surface',
+        profile: 'ui',
+        severity: 'error',
+        summary: 'A `<div>` that draws its own box (background, border, shadow). Suggests a Layout intent that says what the region is.',
+        bad: '<div className="rounded-lg border bg-white p-6">…</div>',
+        good: '<Layout intent="layout.panel">…</Layout>',
+    },
+    {
+        id: 'domain-mismatch',
+        profile: 'ui',
+        severity: 'error',
+        summary: 'An intent rendered by the wrong component, like an action on `<Text>`.',
+        bad: '<Text intent="action.save">Save</Text>',
+        good: '<Action intent="action.save">Save</Action>',
+    },
+    {
+        id: 'leaf-classname',
+        profile: 'ui',
+        severity: 'error',
+        summary: '`className` on `<Text>`, `<Action>`, `<Field>`, `<Media>`, `<Dialog>` or `<Popover>`, which take intents and layout props only.',
+        bad: '<Text intent="text.caption" className="text-red-600">…</Text>',
+        good: '<Text intent="feedback.error">…</Text>',
+    },
+    {
+        id: 'leaf-style',
+        profile: 'ui',
+        severity: 'error',
+        summary: '`style` on a component that takes no style. An inline style overrides the intent just like a className.',
+        bad: '<Action intent="action.save" style={{ color: \'red\' }}>Save</Action>',
+        good: '<Action intent="action.delete">Delete</Action>',
+    },
+    {
+        id: 'layout-visual-class',
+        profile: 'ui',
+        severity: 'error',
+        summary: 'Colours, type or borders in a `<Layout>` className, which is for layout and spacing only.',
+        bad: '<Layout intent="layout.group" className="gap-4 bg-muted">…</Layout>',
+        good: '<Layout intent="layout.panel" className="gap-4">…</Layout>',
+    },
+    {
+        id: 'repeated-tweak',
+        profile: 'ui',
+        severity: 'warning',
+        summary: 'The same layout class added to the same `<Layout>` intent in three or more places, across the whole project. Each is allowed, but a tweak that repeats is a missing intent: points to an intent that already has it, or a ready `add-intent` command. `check --suggest` lists these with the overrides.',
+        bad: '<Layout intent="layout.group" className="gap-4">…</Layout>  // and in 15 other places',
+        good: '<Layout intent="layout.section">…</Layout>',
+    },
+    {
+        id: 'raw-style',
+        profile: 'ui',
+        severity: 'error',
+        summary: 'An inline style that sets colour, type or borders. Layout values and CSS variables are fine.',
+        bad: '<div style={{ color: \'#c00\', fontWeight: 600 }}>…</div>',
+        good: "<Action intent=\"choice.color\" vars={{ '--choice-color': color }} />",
+    },
+    {
+        id: 'unsafe-classname',
+        profile: 'ui',
+        severity: 'warning',
+        summary: 'The escape hatch. A warning with a `// prongs-unsafe: <reason>` comment on the line above, an error without one; counted by `--max-unsafe`.',
+    },
+    {
+        id: 'name-mismatch',
+        profile: 'ui',
+        severity: 'warning',
+        summary: 'An action whose handler, label or text points to a different intent, through the intents’ keywords.',
+        bad: '<Action intent="action.save" onClick={shareArticle}>Share</Action>',
+        good: '<Action intent="action.share" onClick={shareArticle}>Share</Action>',
+    },
+    {
+        id: 'raw-look',
+        profile: 'ui',
+        severity: 'error',
+        summary: 'A plain element with look classes that the other rules do not cover: a `<div>` with text colours, a `<span>` drawn as a dot, a styled `<hr>` or `<iframe>`. Inline SVG and the document root are allowed.',
+        bad: '<span className="h-2 w-2 rounded-full bg-[var(--accent)]" />',
+        good: '<Text intent="text.indicator" aria-label="Unread" />',
+    },
+    {
+        id: 'intent-selector',
+        profile: 'ui',
+        severity: 'error',
+        summary: 'CSS or a class that selects elements by `data-intent`. The attribute is for finding elements (analytics, tests, A/B tools); looks come from the registry.',
+        bad: '[data-intent="action.delete"] { color: red; }',
+        good: "'action.delete': { refs: ['control.destructive'] }",
+    },
+    {
+        id: 'unknown-token',
+        profile: 'ui',
+        severity: 'error',
+        summary: 'A registry class that reads a CSS variable nothing declares, so it resolves to nothing. Variables count as declared when a CSS file sets them or code passes them through `vars`.',
+        bad: "'tone.accent': { binding: { classes: 'text-[var(--brand-blue)]' } }",
+        good: "'tone.accent': { binding: { classes: 'text-primary' } }",
+    },
+    {
+        id: 'raw-value',
+        profile: 'ui',
+        severity: 'warning',
+        summary: 'A colour the theme cannot change: a literal (`bg-[#e5383b]`) or a Tailwind palette colour (`text-sky-700`) in a registry class, or a literal colour set as a CSS variable in `style` or `vars`. White and black are allowed.',
+        bad: "'tone.info': { binding: { classes: 'text-sky-700' } }",
+        good: "'tone.info': { binding: { classes: 'text-info' } }",
+    },
+    {
+        id: 'dynamic-intent',
+        profile: 'ui',
+        severity: 'info',
+        summary: 'An intent computed at runtime, so it could not be checked. A ternary of literals can be.',
+        bad: '<Action intent={intentFor(state)}>…</Action>',
+        good: "<Action intent={following ? 'action.toggle' : 'action.add'}>…</Action>",
+    },
+];

package/dist/tooling/theme.d.ts

@@ -0,0 +1,83 @@
+/**
+ * The theme the registry's classes read: colour tokens plus surfaces that layer themselves. `prongs add` writes
+ * `themeCss()` to theme.css; the values are the project's to change, the names are the
+ * contract the registry and `prongs check` rely on.
+ */
+export type ThemeToken = {
+    name: `--${string}`;
+    light: string;
+    dark: string;
+    /** What the token is for, shown in PRONGS.md and the docs. */
+    description: string;
+    /** The Tailwind colour it becomes (`bg-primary`), when it is a colour. */
+    utility?: string;
+};
+export declare const THEME_TOKENS: readonly ThemeToken[];
+/** How surfaces step. Percentages mix `--foreground` into `--background`. */
+export type SurfaceSettings = {
+    /** How far each level moves towards the foreground, in percent. */
+    step: number;
+    /** The level an overlay (dialog, menu) starts at. */
+    overlay: number;
+    /** How much foreground is in quiet text, in percent of the way from the surface. */
+    muted: number;
+    /** How much foreground is in a surface's hairline. */
+    border: number;
+};
+export declare const SURFACE_SETTINGS: Record<'light' | 'dark', SurfaceSettings>;
+/** Levels a nested surface can reach; deeper nesting stays at the last one. */
+export declare const SURFACE_DEPTH = 4;
+/** The variables a surface sets for whatever is inside it. */
+export declare const SURFACE_TOKENS: readonly ThemeToken[];
+/** The classes that make an element a surface. */
+export declare const SURFACE_CLASSES: readonly [{
+    readonly name: "surface";
+    readonly description: "A raised surface: one level above the surface it sits in.";
+}, {
+    readonly name: "surface-inset";
+    readonly description: "A recess: one level back from the surface it sits in (forward on the page itself).";
+}, {
+    readonly name: "surface-overlay";
+    readonly description: "Floats over the page (dialogs, menus): starts its own stack, whatever it is nested in.";
+}, {
+    readonly name: "surface-page";
+    readonly description: "An element that sets its own --background or --foreground (a themed section, a preview): starts again at level 0 with its colours. It does not paint itself.";
+}];
+/** Every name `theme.css` declares, so `prongs check` can tell a typo from a token. */
+export declare const THEME_VARIABLES: readonly string[];
+/** The CSS `prongs add` writes to theme.css. */
+export declare function themeCss(): string;
+type Oklch = {
+    l: number;
+    c: number;
+    h: number;
+};
+/** Parses `oklch(L C H)` (L as 0–1 or a percentage) or `#rrggbb`. Alpha is not supported. */
+export declare function parseColor(value: string): Oklch | undefined;
+/** color-mix(in oklch, a p, b): `p` is the share of `a`, 0–1. A grey takes the other colour's hue. */
+export declare function mixOklch(a: Oklch, b: Oklch, p: number): Oklch;
+export declare function contrast(a: Oklch, b: Oklch): number;
+export type SurfaceLevel = {
+    /** `page`, `1`…, or `overlay`, `overlay 1`… */
+    name: string;
+    level: number;
+    background: Oklch;
+    /** Contrast of main text, quiet text and the hairline on this level. */
+    text: number;
+    muted: number;
+    border: number;
+    /** Contrast between this level and its hover fill. */
+    hover: number;
+};
+/** Every level the CSS can produce for a background and foreground, with its contrasts. */
+export declare function surfaceLevels(colors: {
+    background: string;
+    foreground: string;
+}, settings: SurfaceSettings): SurfaceLevel[];
+/** `surfaceLevels` for the default theme. */
+export declare function defaultSurfaceLevels(mode: 'light' | 'dark'): SurfaceLevel[];
+/** Contrast of a default token pair, e.g. `--primary-foreground` on `--primary`. */
+export declare function tokenContrast(mode: 'light' | 'dark', fg: string, bg: string): number;
+/** Contrast of a default token's text on every level of the default surfaces. */
+export declare function tokenOnSurfaces(mode: 'light' | 'dark', token: string): number[];
+export {};