commit b36377700d2a890fefaba15be1714c4f1b1eaf93
parent 07ecece421435c6419c5e392406c1dfae721cb30
Author: triesap <tyson@radroots.org>
Date: Mon, 5 Oct 2026 04:34:33 +0000
design: implement deterministic CSS compositions (HCP-012)
- Import approved theme and finite layered compositions once in order.
- Reflow controls and long references with intrinsic layouts and theme tokens.
- Reject decoded Tailwind directives and qualify actual compiled CSS payload.
- Verify source boundaries, narrow browser fixtures and unchanged native inputs.
Diffstat:
6 files changed, 622 insertions(+), 1 deletion(-)
diff --git a/web/src/app.css b/web/src/app.css
@@ -0,0 +1,299 @@
+/* Deterministic compositions. Values that are visual primitives
+ come from theme.css; 0, 100%, fractions and keywords are structural values.
+ No breakpoints, per-component styles or untrusted dynamic class generation. */
+@layer reset, base, components, utilities;
+
+@layer reset {
+ *,
+ *::before,
+ *::after {
+ box-sizing: border-box;
+ }
+ body,
+ h1,
+ h2,
+ h3,
+ p,
+ ul,
+ ol,
+ dl,
+ dd,
+ fieldset {
+ margin: 0;
+ }
+ fieldset {
+ min-inline-size: 0;
+ padding: 0;
+ border: 0;
+ }
+ button,
+ input,
+ textarea,
+ select {
+ font: inherit;
+ }
+ button {
+ cursor: pointer;
+ }
+ button:disabled {
+ cursor: not-allowed;
+ }
+ [hidden] {
+ display: none !important;
+ }
+}
+
+@layer base {
+ html {
+ background: var(--color-page);
+ color: var(--color-text);
+ }
+ body {
+ font-family: var(--font-family-body);
+ font-size: var(--font-size-body);
+ font-weight: var(--font-weight-normal);
+ line-height: var(--line-height-body);
+ }
+ h1 {
+ font-size: var(--font-size-title);
+ }
+ h2,
+ h3 {
+ font-size: var(--font-size-heading);
+ }
+ h1,
+ h2,
+ h3 {
+ font-weight: var(--font-weight-emphasis);
+ line-height: var(--line-height-heading);
+ overflow-wrap: anywhere;
+ }
+ p,
+ li,
+ dt,
+ dd,
+ label {
+ min-inline-size: 0;
+ overflow-wrap: anywhere;
+ }
+ a {
+ color: var(--color-primary);
+ text-underline-offset: var(--space-1);
+ }
+ a:hover {
+ color: var(--color-primary-hover);
+ }
+ :focus-visible {
+ outline: var(--border-focus) solid var(--color-focus);
+ outline-offset: var(--focus-offset);
+ }
+}
+
+@layer components {
+ .page {
+ inline-size: min(100%, var(--measure-page));
+ margin-inline: auto;
+ padding: var(--space-5) var(--space-4);
+ }
+ .page--reading {
+ max-inline-size: var(--measure-form);
+ }
+ .stack {
+ display: flex;
+ flex-direction: column;
+ gap: var(--space-5);
+ min-inline-size: 0;
+ }
+ .stack--tight {
+ gap: var(--space-2);
+ }
+ .cluster {
+ display: flex;
+ flex-wrap: wrap;
+ gap: var(--space-3);
+ align-items: center;
+ }
+ .cluster > * {
+ min-inline-size: 0;
+ max-inline-size: 100%;
+ }
+ .cluster--between {
+ justify-content: space-between;
+ }
+ .navbar {
+ border-block-end: var(--border-hairline) solid var(--color-border);
+ }
+ .navbar__inner {
+ padding-block: var(--space-3);
+ }
+ .brand {
+ font-weight: var(--font-weight-emphasis);
+ color: var(--color-text);
+ text-decoration: none;
+ }
+ .footer {
+ border-block-start: var(--border-hairline) solid var(--color-border);
+ margin-block-start: var(--space-7);
+ }
+ .field {
+ display: flex;
+ flex-direction: column;
+ gap: var(--space-2);
+ min-inline-size: 0;
+ }
+ .field-grid {
+ display: grid;
+ grid-template-columns: repeat(
+ auto-fit,
+ minmax(min(100%, var(--measure-control-min)), 1fr)
+ );
+ gap: var(--space-4);
+ }
+ .label {
+ font-weight: var(--font-weight-emphasis);
+ }
+ .input {
+ inline-size: 100%;
+ min-inline-size: 0;
+ min-block-size: var(--control-min-height);
+ padding: var(--space-2) var(--space-3);
+ color: var(--color-text);
+ background: var(--color-surface);
+ border: var(--border-hairline) solid var(--color-control-border);
+ border-radius: var(--radius-control);
+ }
+ .textarea {
+ min-block-size: var(--textarea-min-height);
+ resize: vertical;
+ }
+ .input[aria-invalid='true'] {
+ border-color: var(--color-danger);
+ }
+ .button {
+ display: inline-flex;
+ align-items: center;
+ justify-content: center;
+ gap: var(--space-2);
+ min-block-size: var(--control-min-height);
+ min-inline-size: 0;
+ max-inline-size: 100%;
+ padding: var(--space-2) var(--space-4);
+ border: var(--border-hairline) solid var(--color-control-border);
+ border-radius: var(--radius-control);
+ font-weight: var(--font-weight-emphasis);
+ text-align: center;
+ text-decoration: none;
+ overflow-wrap: anywhere;
+ }
+ .button--primary {
+ color: var(--color-on-primary);
+ background: var(--color-primary);
+ border-color: var(--color-primary);
+ }
+ .button--primary:hover:not(:disabled) {
+ color: var(--color-on-primary);
+ background: var(--color-primary-hover);
+ border-color: var(--color-primary-hover);
+ }
+ .button--primary:active:not(:disabled) {
+ background: var(--color-primary-active);
+ border-color: var(--color-primary-active);
+ }
+ .button--secondary {
+ color: var(--color-text);
+ background: var(--color-secondary);
+ }
+ .button--secondary:hover:not(:disabled) {
+ color: var(--color-text);
+ background: var(--color-secondary-hover);
+ }
+ .button--secondary:active:not(:disabled) {
+ background: var(--color-secondary-active);
+ }
+ .button:disabled {
+ color: var(--color-disabled-text);
+ background: var(--color-surface-muted);
+ border-color: var(--color-border);
+ }
+ .border-list {
+ list-style: none;
+ padding: 0;
+ border-block-start: var(--border-hairline) solid var(--color-border);
+ }
+ .list-row {
+ min-inline-size: 0;
+ padding-block: var(--space-4);
+ border-block-end: var(--border-hairline) solid var(--color-border);
+ }
+ .notice {
+ padding: var(--space-3);
+ background: var(--color-surface);
+ border: var(--border-hairline) solid var(--color-border);
+ }
+ .notice--error {
+ border-color: var(--color-danger);
+ }
+ .notice--warning {
+ border-color: var(--color-warning);
+ }
+ .facts {
+ display: grid;
+ gap: var(--space-2);
+ min-inline-size: 0;
+ }
+ .facts dt {
+ font-weight: var(--font-weight-emphasis);
+ }
+ .message {
+ min-inline-size: 0;
+ padding: var(--space-3);
+ border-block-end: var(--border-hairline) solid var(--color-border);
+ }
+ .disclosure {
+ min-inline-size: 0;
+ border-block-end: var(--border-hairline) solid var(--color-border);
+ }
+ .disclosure > summary {
+ min-block-size: var(--control-min-height);
+ padding-block: var(--space-2);
+ cursor: pointer;
+ overflow-wrap: anywhere;
+ }
+ .disclosure > :not(summary) {
+ margin-block-end: var(--space-3);
+ }
+ .key {
+ font-family: var(--font-family-mono);
+ overflow-wrap: anywhere;
+ }
+ .description {
+ white-space: pre-wrap;
+ overflow-wrap: anywhere;
+ }
+}
+
+@layer utilities {
+ .text-muted {
+ color: var(--color-text-muted);
+ }
+ .text-small {
+ font-size: var(--font-size-small);
+ }
+ .text-error {
+ color: var(--color-danger);
+ }
+ .text-success {
+ color: var(--color-success);
+ }
+ .visually-hidden:not(:focus):not(:active) {
+ position: absolute;
+ inline-size: var(--size-visually-hidden);
+ block-size: var(--size-visually-hidden);
+ padding: 0;
+ margin: var(--visually-hidden-offset);
+ overflow: hidden;
+ clip-path: inset(50%);
+ white-space: nowrap;
+ border: 0;
+ }
+}
diff --git a/web/src/routes/+layout.svelte b/web/src/routes/+layout.svelte
@@ -1,4 +1,6 @@
<script lang="ts">
+ import '../theme.css';
+ import '../app.css';
import type { Snippet } from 'svelte';
let { children }: { children: Snippet } = $props();
diff --git a/web/tests/e2e/style-contract.spec.ts b/web/tests/e2e/style-contract.spec.ts
@@ -0,0 +1,112 @@
+import { expect, test } from '@playwright/test';
+import { createStaticHarness } from '../integration/harness/static.ts';
+
+// Trusted presentation fixture only: actual compiled CSS, no mock product route.
+const reference = 'TEST_PUBLIC_REFERENCE_' + '0123456789abcdef'.repeat(32);
+const fixture = `<main class="page page--reading stack">
+ <h1>Presentation fixture</h1>
+ <nav class="navbar cluster" aria-label="Fixture navigation"><a class="button button--secondary" href="#form">Fixture controls</a><a class="button button--secondary key" href="#reference">${reference}</a></nav>
+ <form id="form" class="stack">
+ <div class="field-grid">
+ <div class="field"><label class="label" for="query">Fixture query</label><input class="input" id="query" value="${reference}"></div>
+ <div class="field"><label class="label" for="selection">Fixture selection</label><select class="input" id="selection"><option>${reference}</option></select></div>
+ </div>
+ <div class="field"><label class="label" for="text">Fixture text</label><textarea class="input textarea" id="text">${reference}</textarea></div>
+ <div class="cluster"><button type="button" class="button button--primary">Fixture primary</button><button type="button" class="button button--secondary key">${reference}</button><button type="button" disabled class="button button--secondary">Fixture disabled</button></div>
+ </form>
+ <ul class="border-list"><li class="list-row"><p class="key" id="reference">${reference}</p></li></ul>
+ <dl class="facts"><dt>Fixture reference</dt><dd class="key">${reference}</dd></dl>
+ <div class="notice notice--warning"><p class="description">${reference}\nFixture second line</p></div>
+ <article class="message"><p class="description">${reference}</p></article>
+ <details class="disclosure"><summary>Fixture details</summary><p class="key">${reference}</p></details>
+</main>`;
+
+for (const width of [320, 1024]) {
+ test(`compiled compositions reflow with real controls and long references at ${width}px`, async ({
+ browser
+ }) => {
+ const server = await createStaticHarness();
+ const context = await browser.newContext({
+ viewport: { width, height: 900 }
+ });
+ const external: string[] = [];
+ try {
+ await context.route('**/*', (route) => {
+ if (new URL(route.request().url()).origin === server.url)
+ return route.continue();
+ external.push(route.request().url());
+ return route.abort();
+ });
+ const page = await context.newPage();
+ await page.goto(server.url);
+ const sheets = await page
+ .locator('link[rel="stylesheet"]')
+ .evaluateAll((links) =>
+ links.map((link) => (link as HTMLLinkElement).href)
+ );
+ expect(sheets.length).toBeGreaterThan(0);
+ for (const href of sheets) expect(new URL(href).origin).toBe(server.url);
+ await page.setContent(
+ `<!doctype html><html lang="en"><head><title>Style fixture</title>${sheets.map((href) => `<link rel="stylesheet" href="${href}">`).join('')}</head><body>${fixture}</body></html>`,
+ { waitUntil: 'load' }
+ );
+ await expect(page.locator('.page')).toHaveCSS('box-sizing', 'border-box');
+ await expect(page.locator('.key').first()).toHaveCSS(
+ 'overflow-wrap',
+ 'anywhere'
+ );
+ const measure = async () =>
+ page.evaluate(() => ({
+ width: window.innerWidth,
+ scroll: document.documentElement.scrollWidth,
+ page: document.querySelector('main')!.getBoundingClientRect().width,
+ controls: Array.from(
+ document.querySelectorAll(
+ 'input,textarea,select,button,a.button,summary'
+ )
+ ).map((element) => {
+ const rect = element.getBoundingClientRect();
+ return { height: rect.height, left: rect.left, right: rect.right };
+ })
+ }));
+ const assertFit = (result: Awaited<ReturnType<typeof measure>>) => {
+ expect(result.scroll).toBeLessThanOrEqual(result.width);
+ expect(result.page).toBeLessThanOrEqual(Math.min(width, 672));
+ expect(result.controls.length).toBe(9);
+ for (const control of result.controls) {
+ expect(control.height).toBeGreaterThanOrEqual(44);
+ expect(control.left).toBeGreaterThanOrEqual(0);
+ expect(control.right).toBeLessThanOrEqual(width);
+ }
+ };
+ const closed = await measure();
+ assertFit(closed);
+ await page.getByLabel('Fixture query').focus();
+ await expect(page.getByLabel('Fixture query')).toBeFocused();
+ await expect(page.getByLabel('Fixture query')).toHaveCSS(
+ 'outline-style',
+ 'solid'
+ );
+ await page.keyboard.press('Tab');
+ await expect(page.getByLabel('Fixture selection')).toBeFocused();
+ await page.getByText('Fixture details', { exact: true }).click();
+ await expect(page.locator('details')).toHaveAttribute('open', '');
+ const opened = await measure();
+ assertFit(opened);
+ console.log(
+ JSON.stringify({
+ fixture: 'HCP012_PRESENTATION_ONLY',
+ sheets,
+ closed,
+ opened
+ })
+ );
+ expect(external).toEqual([]);
+ } finally {
+ await context.close();
+ await server.close();
+ }
+ expect(context.pages()).toHaveLength(0);
+ expect(server.state()).toEqual({ listening: false, childProcesses: 0 });
+ });
+}
diff --git a/web/tests/provenance/output.test.mjs b/web/tests/provenance/output.test.mjs
@@ -101,7 +101,16 @@ await test('actual output qualification', { timeout: 30000 }, async (t) => {
async (t) => {
const f = await fixture(t);
const files = await f.audit();
- assert.equal(files.length, 15);
+ // The once-imported theme/compositions add one actual compiled CSS asset.
+ assert.equal(files.length, 16);
+ assert.equal(files.filter((name) => name.endsWith('.css')).length, 1);
+ assert.ok(
+ files.some((name) =>
+ /^_app\/immutable\/assets\/[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.css$/.test(
+ name
+ )
+ )
+ );
assert.ok(files.includes('200.html'));
const pkg = JSON.parse(
await readFile(path.join(f.web, 'package.json'), 'utf8')
diff --git a/web/tests/unit/style-contract.test.ts b/web/tests/unit/style-contract.test.ts
@@ -0,0 +1,193 @@
+import { readFileSync } from 'node:fs';
+import {
+ copyFile,
+ mkdir,
+ mkdtemp,
+ rm,
+ symlink,
+ writeFile
+} from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+import { describe, expect, it } from 'vitest';
+
+const root = fileURLToPath(new URL('../../', import.meta.url));
+const layout = readFileSync(
+ path.join(root, 'src/routes/+layout.svelte'),
+ 'utf8'
+);
+const theme = readFileSync(path.join(root, 'src/theme.css'), 'utf8');
+const app = () => readFileSync(path.join(root, 'src/app.css'), 'utf8');
+
+describe('finite two-file style contract', () => {
+ it('imports theme then compositions once at the root layout', () => {
+ expect(
+ [...layout.matchAll(/import\s+['"]([^'"]+\.css)['"]/g)].map((m) => m[1])
+ ).toEqual(['../theme.css', '../app.css']);
+ });
+ it('provides the declared finite composition vocabulary and layer order', () => {
+ const css = app();
+ expect(css).toContain('@layer reset, base, components, utilities;');
+ for (const name of [
+ 'page',
+ 'page--reading',
+ 'stack',
+ 'stack--tight',
+ 'cluster',
+ 'navbar',
+ 'field',
+ 'label',
+ 'input',
+ 'textarea',
+ 'button',
+ 'button--primary',
+ 'button--secondary',
+ 'border-list',
+ 'list-row',
+ 'facts',
+ 'notice',
+ 'message',
+ 'disclosure',
+ 'text-muted',
+ 'visually-hidden'
+ ]) {
+ expect(css).toMatch(new RegExp('\\.' + name + '(?=[\\s:{,.])'));
+ }
+ expect(css).not.toMatch(
+ /@media|@import|url\(|#[0-9a-f]{3,8}\b|\b(?:rgb|hsl)a?\(|(?:^|[;{])\s*--[\w-]+\s*:/im
+ );
+ const tokens = new Set(
+ [...theme.matchAll(/(--[\w-]+)\s*:/g)].map((m) => m[1])
+ );
+ for (const match of css.matchAll(/var\((--[\w-]+)\)/g))
+ expect(tokens.has(match[1])).toBe(true);
+ expect(css).not.toMatch(/\b\d*\.?\d+(?:px|rem|em|ch|vh|vw)\b/);
+ });
+});
+
+async function audit(extra: { name: string; content: string }) {
+ const directory = await mkdtemp(path.join(tmpdir(), 'hcp012 styles '));
+ try {
+ await mkdir(path.join(directory, 'tools'));
+ await mkdir(path.join(directory, 'src/routes'), { recursive: true });
+ for (const name of [
+ 'package.json',
+ 'tsconfig.json',
+ 'vite.config.ts',
+ 'tools/check-source.mjs',
+ 'tools/source-boundaries.mjs'
+ ])
+ await copyFile(path.join(root, name), path.join(directory, name));
+ await symlink(
+ path.join(root, 'node_modules'),
+ path.join(directory, 'node_modules')
+ );
+ await writeFile(path.join(directory, 'src/theme.css'), theme);
+ await writeFile(
+ path.join(directory, 'src/app.css'),
+ '@layer reset, base, components, utilities;'
+ );
+ await writeFile(
+ path.join(directory, 'src/routes/+layout.svelte'),
+ '<script>import "../theme.css"; import "../app.css";</script>'
+ );
+ await mkdir(path.dirname(path.join(directory, extra.name)), {
+ recursive: true
+ });
+ await writeFile(path.join(directory, extra.name), extra.content);
+ const result = spawnSync(process.execPath, ['tools/check-source.mjs'], {
+ cwd: directory,
+ encoding: 'utf8',
+ timeout: 8000
+ });
+ expect(result.error).toBeUndefined();
+ return result;
+ } finally {
+ await rm(directory, { recursive: true, force: true });
+ }
+}
+
+describe('actual source guard rejects forbidden styles', () => {
+ it('admits the isolated paired stylesheet positive control', async () => {
+ expect(
+ (
+ await audit({
+ name: 'src/routes/+page.svelte',
+ content: '<p class="notice">Test</p>'
+ })
+ ).status
+ ).toBe(0);
+ });
+ it('admits ordinary layered compositions and ignores comments', async () => {
+ expect(
+ (
+ await audit({
+ name: 'src/app.css',
+ content:
+ '/* @tailwind utilities; */ @layer components { .notice { padding: var(--space-2); } }'
+ })
+ ).status
+ ).toBe(0);
+ });
+ it.each([
+ 'tailwind',
+ 'apply',
+ 'theme',
+ 'utility',
+ 'variant',
+ 'custom-variant',
+ 'config',
+ 'plugin',
+ 'source',
+ 'reference'
+ ])('rejects Tailwind @%s', async (directive) => {
+ const result = await audit({
+ name: 'src/app.css',
+ content: `@${directive} fixture;`
+ });
+ expect(result.status).not.toBe(0);
+ expect(result.stderr).toContain('Tailwind CSS directives are forbidden');
+ });
+ it.each([
+ '@\\74 ailwind utilities;',
+ '@tai/**/lwind utilities;',
+ '.notice { @\\61 pply bg-white; }'
+ ])('rejects decoded Tailwind syntax %s', async (content) => {
+ const result = await audit({ name: 'src/app.css', content });
+ expect(result.status).not.toBe(0);
+ expect(result.stderr).toContain('Tailwind CSS directives are forbidden');
+ });
+ it.each([
+ [
+ 'component CSS',
+ 'src/routes/+page.svelte',
+ '<p>Test</p><style>p { color: red; }</style>'
+ ],
+ [
+ 'inline attribute',
+ 'src/routes/+page.svelte',
+ '<p style="color: red">Test</p>'
+ ],
+ [
+ 'inline directive',
+ 'src/routes/+page.svelte',
+ '<p style:color="red">Test</p>'
+ ],
+ [
+ 'CSS in JavaScript',
+ 'src/routes/+page.ts',
+ 'export function decorate(element: HTMLElement) { element.style.color = "red"; }'
+ ],
+ ['Tailwind import', 'src/routes/+page.ts', 'import "tailwindcss";'],
+ [
+ 'Tailwind directives',
+ 'src/app.css',
+ '@tailwind utilities; .notice { @apply bg-white; }'
+ ]
+ ])('rejects %s', async (_name, name, content) => {
+ const result = await audit({ name, content });
+ expect(result.status, result.stdout + result.stderr).not.toBe(0);
+ });
+});
diff --git a/web/tools/source-boundaries.mjs b/web/tools/source-boundaries.mjs
@@ -1456,6 +1456,12 @@ export async function auditSource(root) {
.replace(/\/\*[\s\S]*?\*\//g, '');
if (/@import\b|url\s*\(/i.test(css))
complain(file, 'CSS import/url loading is forbidden');
+ if (
+ /@(?:tailwind|apply|theme|utility|variant|custom-variant|config|plugin|source|reference)\b/i.test(
+ css
+ )
+ )
+ complain(file, 'Tailwind CSS directives are forbidden');
}
const html = name === 'src/app.html';
if (!codeExtension.test(file) && !html) continue;