app

Local-first trade for farms and co-ops
git clone https://radroots.dev/git/app.git
Log | Files | Refs | README | LICENSE

commit 07ecece421435c6419c5e392406c1dfae721cb30
parent 68eb90691580b132d088bcecc13acc43e3f2d45d
Author: triesap <tyson@radroots.org>
Date:   Mon,  5 Oct 2026 04:01:06 +0000

design: install the approved theme primitives (HCP-011)

- Add the approved palette typography spacing and control primitives
- Verify source contrast measures local fonts and decorative boundaries
- Admit unimported theme primitives before the CSS composition checkpoint
- Preserve strict paired stylesheet imports and all native inputs

Diffstat:
Aweb/src/theme.css | 57+++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Mweb/tests/provenance/source-boundaries.test.mjs | 91+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Aweb/tests/unit/theme.test.ts | 280+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Mweb/tools/source-boundaries.mjs | 6++++++
4 files changed, 434 insertions(+), 0 deletions(-)

diff --git a/web/src/theme.css b/web/src/theme.css @@ -0,0 +1,57 @@ +/* Approved primitives. Compositions and once-only imports belong to app.css consumers. */ +@layer reset, base, components, utilities; + +@layer base { + :root { + color-scheme: light; + --color-page: #ffffff; + --color-surface: var(--color-page); + --color-surface-muted: #f4f5f7; + --color-text: #202124; + --color-text-muted: #5e6268; + --color-border: #d4d7dc; + --color-control-border: #73777f; + --color-primary: #1769c2; + --color-primary-hover: #12559e; + --color-primary-active: #104984; + --color-on-primary: var(--color-page); + --color-secondary: #f2f3f5; + --color-secondary-hover: #e6e8eb; + --color-secondary-active: #d9dde2; + --color-focus: #005fcc; + --color-danger: #9d2424; + --color-warning: #76520b; + --color-success: #246234; + --color-disabled-text: #62666d; + --font-family-body: + -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; + --font-family-mono: ui-monospace, 'SFMono-Regular', Consolas, monospace; + --font-size-small: 0.875rem; + --font-size-body: 1rem; + --font-size-title: 1.625rem; + --font-size-heading: 1.125rem; + --font-weight-normal: 400; + --font-weight-emphasis: 600; + --line-height-body: 1.5; + --line-height-heading: 1.25; + --space-1: 0.25rem; + --space-2: 0.5rem; + --space-3: 0.75rem; + --space-4: 1rem; + --space-5: 1.5rem; + --space-6: 2rem; + --space-7: 3rem; + --border-hairline: 1px; + --border-focus: 2px; + --focus-offset: 2px; + --radius-control: 4px; + --control-min-height: 2.75rem; + --textarea-min-height: 7rem; + --measure-page: 64rem; + --measure-form: 42rem; + --measure-control-min: 14rem; + --measure-key: 32ch; + --size-visually-hidden: 1px; + --visually-hidden-offset: -1px; + } +} diff --git a/web/tests/provenance/source-boundaries.test.mjs b/web/tests/provenance/source-boundaries.test.mjs @@ -310,6 +310,97 @@ for (const [name, content, diagnostic] of [ reject(execute(), diagnostic); }); }); +for (const themePresent of [false, true]) + test(`HCP011 admits ${themePresent ? 'unimported theme primitives' : 'bootstrap without CSS'}`, async () => { + await fixture(async ({ put, execute }) => { + if (themePresent) + await put('src/theme.css', ':root { --color-page: #ffffff; }'); + await put('src/routes/+layout.svelte', '<p>shell</p>'); + const result = execute(); + assert.equal(result.status, 0, result.stdout + result.stderr); + }); + }); + +for (const [name, themePresent, appPresent, owner, imports, diagnostic] of [ + ['app only', false, true, '+layout.svelte', '', /exactly once/], + [ + 'theme imported without app', + true, + false, + '+layout.svelte', + 'import "../theme.css";', + /exactly once/ + ], + [ + 'app imported without theme', + false, + true, + '+layout.svelte', + 'import "../app.css";', + /exactly once/ + ], + ['both missing imports', true, true, '+layout.svelte', '', /exactly once/], + [ + 'theme-only partial import', + true, + true, + '+layout.svelte', + 'import "../theme.css";', + /exactly once/ + ], + [ + 'app-only partial import', + true, + true, + '+layout.svelte', + 'import "../app.css";', + /exactly once/ + ], + [ + 'duplicate import', + true, + true, + '+layout.svelte', + 'import "../theme.css"; import "../theme.css"; import "../app.css";', + /exactly once/ + ], + [ + 'reversed import', + true, + true, + '+layout.svelte', + 'import "../app.css"; import "../theme.css";', + /exactly once/ + ], + [ + 'wrong owner', + true, + true, + '+page.svelte', + 'import "../theme.css"; import "../app.css";', + /root layout/ + ] +]) + test(`HCP011 rejects CSS lifecycle ${name}`, async () => { + await fixture(async ({ put, execute }) => { + if ( + typeof owner !== 'string' || + typeof imports !== 'string' || + !(diagnostic instanceof RegExp) + ) + throw new Error('Invalid CSS lifecycle case'); + if (themePresent) + await put('src/theme.css', ':root { --color-page: #ffffff; }'); + if (appPresent) + await put('src/app.css', 'p { color: var(--color-page); }'); + await put( + `src/routes/${owner}`, + `<script>${imports}</script><p>shell</p>` + ); + reject(execute(), diagnostic); + }); + }); + test('two CSS paths must be imported once in order by root layout', async () => { await fixture(async ({ put, execute }) => { await put('src/theme.css', ':root { --color: black }'); diff --git a/web/tests/unit/theme.test.ts b/web/tests/unit/theme.test.ts @@ -0,0 +1,280 @@ +import { readFileSync } from 'node:fs'; +import { describe, expect, it } from 'vitest'; + +// This standalone contract records approved primitives, not parent-file inputs. +const approved = { + '--color-page': '#ffffff', + '--color-surface': 'var(--color-page)', + '--color-surface-muted': '#f4f5f7', + '--color-text': '#202124', + '--color-text-muted': '#5e6268', + '--color-border': '#d4d7dc', + '--color-control-border': '#73777f', + '--color-primary': '#1769c2', + '--color-primary-hover': '#12559e', + '--color-primary-active': '#104984', + '--color-on-primary': 'var(--color-page)', + '--color-secondary': '#f2f3f5', + '--color-secondary-hover': '#e6e8eb', + '--color-secondary-active': '#d9dde2', + '--color-focus': '#005fcc', + '--color-danger': '#9d2424', + '--color-warning': '#76520b', + '--color-success': '#246234', + '--color-disabled-text': '#62666d', + '--font-family-body': + "-apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif", + '--font-family-mono': "ui-monospace, 'SFMono-Regular', Consolas, monospace", + '--font-size-small': '0.875rem', + '--font-size-body': '1rem', + '--font-size-title': '1.625rem', + '--font-size-heading': '1.125rem', + '--font-weight-normal': '400', + '--font-weight-emphasis': '600', + '--line-height-body': '1.5', + '--line-height-heading': '1.25', + '--space-1': '0.25rem', + '--space-2': '0.5rem', + '--space-3': '0.75rem', + '--space-4': '1rem', + '--space-5': '1.5rem', + '--space-6': '2rem', + '--space-7': '3rem', + '--border-hairline': '1px', + '--border-focus': '2px', + '--focus-offset': '2px', + '--radius-control': '4px', + '--control-min-height': '2.75rem', + '--textarea-min-height': '7rem', + '--measure-page': '64rem', + '--measure-form': '42rem', + '--measure-control-min': '14rem', + '--measure-key': '32ch', + '--size-visually-hidden': '1px', + '--visually-hidden-offset': '-1px' +} as const; + +type Token = keyof typeof approved; + +function source(): string { + return readFileSync(new URL('../../src/theme.css', import.meta.url), 'utf8'); +} + +// Deliberately accepts only this small primitive-only CSS grammar. +function primitives(css: string): Map<string, string> { + const clean = css.replace(/\/\*[\s\S]*?\*\//g, '').trim(); + const root = + /^@layer reset, base, components, utilities;\s*@layer base\s*\{\s*:root\s*\{([^{}]*)\}\s*\}$/.exec( + clean + ); + if (!root) + throw new Error( + 'Theme must contain only ordered layers and one base :root' + ); + const entries = new Map<string, string>(); + for (const declaration of root[1] + .split(';') + .map((item) => item.trim()) + .filter(Boolean)) { + const pair = /^(color-scheme|--[a-z][a-z0-9-]*):\s*(.+)$/.exec(declaration); + if (!pair || entries.has(pair[1])) + throw new Error(`Invalid or duplicate primitive: ${declaration}`); + entries.set(pair[1], pair[2].trim()); + } + return entries; +} + +function color(tokens: Map<string, string>, name: Token): string { + const value = tokens.get(name); + const alias = /^var\((--[a-z-]+)\)$/.exec(value ?? ''); + // The only approved color aliases point to the literal white page primitive. + const resolved = alias ? tokens.get(alias[1]) : value; + if (!resolved || !/^#[0-9a-f]{6}$/i.test(resolved)) + throw new Error(`Invalid color: ${name}`); + return resolved; +} + +// WCAG 2.2 sRGB relative luminance and contrast, for source arithmetic only: +// https://www.w3.org/TR/WCAG22/#dfn-relative-luminance +function linear(channel: number): number { + return channel <= 0.04045 + ? channel / 12.92 + : ((channel + 0.055) / 1.055) ** 2.4; +} + +function luminance(hex: string): number { + const channels = [1, 3, 5].map((offset) => + linear(parseInt(hex.slice(offset, offset + 2), 16) / 255) + ); + return 0.2126 * channels[0] + 0.7152 * channels[1] + 0.0722 * channels[2]; +} + +function contrast(foreground: string, background: string): number { + const a = luminance(foreground); + const b = luminance(background); + return (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05); +} + +const surfaces: Token[] = [ + '--color-page', + '--color-surface', + '--color-surface-muted' +]; +const primary: Token[] = [ + '--color-primary', + '--color-primary-hover', + '--color-primary-active' +]; +const secondary: Token[] = [ + '--color-secondary', + '--color-secondary-hover', + '--color-secondary-active' +]; +const text: Token[] = [ + '--color-text', + '--color-text-muted', + '--color-danger', + '--color-warning', + '--color-success' +]; + +describe('approved theme primitives (source checks, not rendered accessibility)', () => { + it('declares exactly one approved value per primitive in one root', () => { + expect(Object.fromEntries(primitives(source()))).toEqual({ + 'color-scheme': 'light', + ...approved + }); + }); + + it('rejects duplicate declarations even when their values are identical', () => { + expect(() => + primitives( + source().replace( + '--color-page:', + '--color-page: #ffffff; --color-page:' + ) + ) + ).toThrow('duplicate primitive'); + }); + + it('contains only local system font stacks and no font or external style loading', () => { + const css = source(); + const tokens = primitives(css); + expect(tokens.get('--font-family-body')).toBe( + approved['--font-family-body'] + ); + expect(tokens.get('--font-family-mono')).toBe( + approved['--font-family-mono'] + ); + expect(css).not.toMatch(/@import|@font-face|url\s*\(|https?:|\/\//i); + }); + + it('preserves the page/form measures and 44px control goal at a 16px root', () => { + const tokens = primitives(source()); + expect(tokens.get('--measure-page')).toBe('64rem'); + expect(tokens.get('--measure-form')).toBe('42rem'); + expect(tokens.get('--control-min-height')).toBe('2.75rem'); + expect(parseFloat(tokens.get('--control-min-height')!) * 16).toBe(44); + }); + + it('checks the luminance oracle at both transfer branches and known contrast anchors', () => { + expect(linear(0.04045)).toBeCloseTo(0.0031308049535603713, 15); + expect(linear(0.04046)).toBeCloseTo(0.003131594552688991, 15); + expect(luminance('#ff0000')).toBeCloseTo(0.2126, 12); + expect(luminance('#00ff00')).toBeCloseTo(0.7152, 12); + expect(luminance('#0000ff')).toBeCloseTo(0.0722, 12); + expect(contrast('#000000', '#ffffff')).toBe(21); + expect(contrast('#ffffff', '#000000')).toBe(21); + expect(contrast('#777777', '#777777')).toBe(1); + expect(contrast('#777777', '#ffffff')).toBeLessThan(4.5); + expect(contrast('#767676', '#ffffff')).toBeGreaterThanOrEqual(4.5); + }); + + it.each( + text.flatMap((foreground) => + surfaces.map((background) => [foreground, background] as const) + ) + )('ordinary %s text on %s reaches 4.5:1', (foreground, background) => { + const tokens = primitives(source()); + expect( + contrast(color(tokens, foreground), color(tokens, background)) + ).toBeGreaterThanOrEqual(4.5); + }); + + it.each(primary)('white primary text on %s reaches 4.5:1', (background) => { + const tokens = primitives(source()); + expect( + contrast(color(tokens, '--color-on-primary'), color(tokens, background)) + ).toBeGreaterThanOrEqual(4.5); + }); + + it.each( + primary.flatMap((foreground) => + surfaces.map((background) => [foreground, background] as const) + ) + )('%s link text on %s reaches 4.5:1', (foreground, background) => { + const tokens = primitives(source()); + expect( + contrast(color(tokens, foreground), color(tokens, background)) + ).toBeGreaterThanOrEqual(4.5); + }); + + it.each(secondary)( + 'secondary text and useful boundary on %s remain distinct', + (background) => { + const tokens = primitives(source()); + expect( + contrast(color(tokens, '--color-text'), color(tokens, background)) + ).toBeGreaterThanOrEqual(4.5); + expect( + contrast( + color(tokens, '--color-control-border'), + color(tokens, background) + ) + ).toBeGreaterThanOrEqual(3); + // Gray fills alone do not identify the control; later compositions must use its stronger border. + expect( + contrast(color(tokens, background), color(tokens, '--color-page')) + ).toBeLessThan(3); + } + ); + + it.each(surfaces)( + 'useful control boundaries and offset focus on %s reach 3:1', + (background) => { + const tokens = primitives(source()); + for (const foreground of [ + '--color-control-border', + '--color-focus', + ...primary + ] as Token[]) { + expect( + contrast(color(tokens, foreground), color(tokens, background)) + ).toBeGreaterThanOrEqual(3); + } + } + ); + + it.each(surfaces)( + 'decorative hairlines on %s are not admitted as useful control boundaries', + (background) => { + const tokens = primitives(source()); + expect(color(tokens, '--color-border')).not.toBe( + color(tokens, '--color-control-border') + ); + expect( + contrast(color(tokens, '--color-border'), color(tokens, background)) + ).toBeLessThan(3); + } + ); + + it('measures disabled text on its secondary fill without making an active-control compliance claim', () => { + const tokens = primitives(source()); + expect( + contrast( + color(tokens, '--color-disabled-text'), + color(tokens, '--color-secondary') + ) + ).toBeGreaterThanOrEqual(4.5); + }); +}); diff --git a/web/tools/source-boundaries.mjs b/web/tools/source-boundaries.mjs @@ -2066,8 +2066,14 @@ export async function auditSource(root) { const presentCss = [...allowedCss].filter((file) => files.has(path.join(root, file)) ); + // Primitives may precede compositions; importing either file activates the complete pair contract. + const unimportedTheme = + presentCss.length === 1 && + presentCss[0] === 'src/theme.css' && + cssImports.length === 0; if ( presentCss.length && + !unimportedTheme && (presentCss.length !== 2 || cssImports.join(',') !== 'src/theme.css,src/app.css') )