feat(core): adopt attribute grammar for root and surface contracts

Author: monospaced

apps/storybook/.storybook/preview.ts

@@ -52,7 +52,7 @@ const preview: Preview = {
                 ${storyHtml}
               </div>
             `,
-            surface: context.globals.surface,
+            variant: context.globals.surface,
           })}
         `,
         dir: context.globals.direction,

docs/CONSTRAINTS.md

@@ -71,6 +71,10 @@ Resolver adapter details live in `packages/system/scripts/README.md`.
 ## Components Package Constraints (Alpha)
 
 - `packages/core/` is the canonical package boundary for component contracts built on token outputs.
+- Component markup grammar (SSR-first):
+  - structural semantics use classes (function-focused nouns, not appearance naming).
+  - state/variant semantics use attributes (for example `data-variant`, `data-size`, ARIA state attrs).
+  - public renderer props should map directly to emitted DOM semantics (props -> attributes).
 - Component implementation model:
   - components that do not require runtime JS behavior should be authored as pure SSR renderers that emit native HTML.
   - components that do require runtime JS behavior may be authored as web-components.
@@ -183,15 +187,15 @@ Resolver adapter details live in `packages/system/scripts/README.md`.
 - CSS layering contract (`@layer clbr, clbr.brand, clbr.root, clbr.components;`) is normative and must be preserved in distributed bundles.
 - Root scoping contract:
   - all token usage must live under a `.clbr` scope root
-  - select a brand via `.clbr-brand-<brand>` on the same scope root
+  - select a brand via `data-brand="<brand>"` on the same scope root
 - Theme forcing contract:
-  - `.clbr-theme-dark` and `.clbr-theme-light` force mode on the scoped brand root
-  - without force classes, theme follows authored media query behavior
+  - `data-theme="dark"` and `data-theme="light"` force mode on the scoped brand root
+  - without force attributes, theme follows authored media query behavior
 - Surface contract:
-  - `.clbr-surface-brand` is a descendant surface scope inside a brand root
+  - `.surface[data-variant="brand"]` is a descendant surface scope inside a brand root
 - Multi-brand on one page is supported:
-  - use isolated wrapper roots per brand (`.clbr.clbr-brand-msrd`, `.clbr.clbr-brand-wrfr`, etc.)
-  - do not mix multiple brand classes on the same scope root
+  - use isolated wrapper roots per brand (`.clbr[data-brand="msrd"]`, `.clbr[data-brand="wrfr"]`, etc.)
+  - do not mix multiple brands on the same scope root
 
 ## Domain Conventions
 

docs/PLANNING.md

@@ -27,13 +27,15 @@ What we could working on next.
 
 Everything we could attempt given sufficient time and resources.
 
-### Deterministic sorting (linting)
+### Tokens evolution
+
+#### Deterministic sorting (linting)
 
 - JS import/export ordering via ESLint autofix
 - JSON key-order enforcement for selected token paths (including top-key conventions like `$schema` / `$type` / `$description` / `default`)
 - Alphabetical sorting
 
-### Machine-readable intent
+#### Machine-readable intent
 
 - Expand token/group `$description` coverage for intent guidance:
   - usage guidance for humans/agents
@@ -43,14 +45,14 @@ Everything we could attempt given sufficient time and resources.
   - stable fields for tooling/agents beyond prose descriptions
   - worked examples where intent is easy to misuse
 
-### Design model evolution
+#### Design model evolution
 
 - Light/dark inverse surfaces
 - `density` context (class-based in CSS) — current size context grid/spacing is broadly editorial/comfortable in nature, this may be fine, but may want to add a ui/compact mode
 - Border and Transition DTCG Composites
 - Give wireframe theme an actual design
 
-### Style Dictionary DTCG 2025.10 gaps
+#### Style Dictionary DTCG 2025.10 gaps
 
 [Support for DTCG v2025.10](https://github.com/style-dictionary/style-dictionary/issues/1590)
 
@@ -59,45 +61,47 @@ Everything we could attempt given sufficient time and resources.
 - Revisit resolver bridge scope once Style Dictionary lands native DTCG resolver support:
   - reduce/remove custom resolver->SD source adaptation where SD can natively consume resolver semantics
 
-### Export target evolution
+#### JSON export target
+
+Define a stable JSON artifact contract for downstream consumers (including docs) so metadata and token data can be consumed without coupling to internal bridge/build intermediates. Likely `packages/tokens` / `@measured/calibrate-tokens`.
+
+Note: pipeline is currently hard-coded to CSS; probably add optional `--formats` in `packages/system/scripts/pipeline/index.mjs` when implementing a second export target.
+
+#### Export target evolution
 
 1. Penpot
 1. Figma
 1. VS Code token lookup artifact
 1. iOS
 1. Android
 
-Note: pipeline is currently hard-coded to CSS; probably add optional `--formats` in `packages/system/scripts/pipeline/index.mjs` when implementing a second export target.
+### Further evolution
 
-### Automated checks
+#### Assets package
 
-Stylelint/ESLint/axe; token-name lint rules; forbid raw hex/px; PR templates require a11y notes, screenshots, and before/after diffs.
+Decide whether shared fonts/images should ship as a dedicated package and define what is stable asset API vs implementation detail.
 
-### JSON export target
+#### Shareable automated checks
 
-Define a stable JSON artifact contract for downstream consumers (including docs) so metadata and token data can be consumed without coupling to internal bridge/build intermediates.
+Stylelint/ESLint/axe configs; token-name lint rules; forbid raw hex/px; PR templates require a11y notes, screenshots, and before/after diffs.
 
-### Minimal viable publish
+#### Minimal viable publish
 
 Define the minimum scripts, workflow, and release notes needed to publish initial alpha packages and unblock downstream adoption tasks.
 
-### Documentation website (`apps/documentation`)
-
-Stand up a docs site that consumes published token/component packages and serves as the canonical reference for usage, contracts, and examples.
+#### Documentation website (`apps/documentation`)
 
-### Assets package
-
-Decide whether shared fonts/images should ship as a dedicated package and define what is stable asset API vs implementation detail.
+Stand up a docs site that consumes published token/component packages and serves as the canonical reference for usage, contracts, and examples. Deploy to `http://calibrate.msrd.dev`, `apps/storybook` can deploy to `http://calibrate.msrd.dev/storybook/`
 
-### CLI bootstrap tool
+#### CLI bootstrap tool (`@measured/calibrate`)
 
 Scope a `calibrate` bootstrap CLI for fast project scaffolding with sensible defaults for tokens, components, and optional assets.
 
-### Framework adapters
+#### Framework adapters (e.g. `@measured/calibrate-react`)
 
 Identify the minimum adapter surface needed to consume token/component contracts ergonomically across target frameworks.
 
-### MCP/API
+#### MCP/API
 
 Evaluate whether an MCP/API distribution path adds clear value beyond package and CLI workflows for token discovery and integration.
 
@@ -224,3 +228,8 @@ _This section is a historical completion record; some entries may describe decis
   - script ownership moved to `apps/storybook`, with root convenience aliases (`storybook`, `storybook:build`)
   - static output normalized to `apps/storybook/storybook-static`
   - CI expanded with dedicated Storybook build job
+- Class/attribute grammar applied to root + surface contracts:
+  - structural semantics use classes; state/variant semantics use attributes
+  - `root` now emits `.clbr` + `data-brand` (+ optional `data-theme`)
+  - `surface` now emits `.surface` + `data-variant` (default included)
+  - token resolver selectors and generated brand CSS updated to match attribute grammar

packages/core/src/components/root/root.css

@@ -1,9 +1,11 @@
 @layer clbr.root {
   .clbr {
+    all: initial;
     background-color: var(--clbr-color-background-default);
     background-repeat: no-repeat;
     box-sizing: border-box;
     color: var(--clbr-color-foreground-default);
+    display: block;
     font-family: var(--clbr-typography-font-family-default);
     font-feature-settings: "ss03" 1;
     font-optical-sizing: none;
@@ -36,6 +38,12 @@
   }
 
   :where(.clbr) {
+    :where(:not(svg, svg *)),
+    :where(*::before),
+    :where(*::after) {
+      all: revert;
+    }
+
     *,
     *::before,
     *::after {

packages/core/src/components/root/root.test.ts

@@ -2,30 +2,31 @@ import { describe, expect, it } from "vitest";
 import { renderClbrRoot } from "./root";
 
 describe("renderClbrRoot", () => {
-  it("uses msrd brand by default", () => {
+  it("renders root class and default data-brand when brand is omitted", () => {
     const html = renderClbrRoot({ children: "<p>content</p>" });
-    expect(html).toContain('class="clbr clbr-brand-msrd"');
+    expect(html).toContain('class="clbr"');
+    expect(html).toContain('data-brand="msrd"');
   });
 
-  it("applies explicit brand class", () => {
+  it("applies explicit brand attribute", () => {
     const html = renderClbrRoot({
       brand: "wrfr",
       children: "<p>content</p>",
     });
-    expect(html).toContain('class="clbr clbr-brand-wrfr"');
+    expect(html).toContain('data-brand="wrfr"');
   });
 
-  it("renders theme class when provided", () => {
+  it("renders theme attribute when provided", () => {
     const html = renderClbrRoot({
       children: "<p>content</p>",
       theme: "dark",
     });
-    expect(html).toContain("clbr-theme-dark");
+    expect(html).toContain('data-theme="dark"');
   });
 
-  it("does not render theme class when omitted", () => {
+  it("does not render theme attribute when omitted", () => {
     const html = renderClbrRoot({ children: "<p>content</p>" });
-    expect(html).not.toContain("clbr-theme-");
+    expect(html).not.toContain("data-theme=");
   });
 
   it("renders dir when provided", () => {

packages/core/src/components/root/root.ts

@@ -1,5 +1,3 @@
-import { cx } from "../../helpers/cx";
-
 export type ClbrBrand = "msrd" | "wrfr";
 export type ClbrDirection = "ltr" | "rtl";
 export type ClbrTheme = "light" | "dark";
@@ -26,25 +24,23 @@ export interface ClbrRootProps {
 /**
  * SSR renderer for the Calibrate root wrapper.
  *
- * Emits a `<div>` with Calibrate root classes, optional `dir`/`lang`
- * attributes, and optional `clbr-theme-{theme}` class, then injects the
- * provided HTML content inside.
+ * Emits a `<div>` with the Calibrate root class, required `data-brand`,
+ * optional `data-theme`, and optional `dir`/`lang` attributes, then injects
+ * the provided HTML content inside.
  *
  * @param props - Root wrapper configuration and inner HTML content.
  * @returns HTML string for the Calibrate root wrapper.
  */
 export function renderClbrRoot(props: ClbrRootProps): string {
   const { brand = "msrd", children, dir, lang, theme } = props;
 
-  const classAttr = cx(
-    "clbr",
-    `clbr-brand-${brand}`,
-    theme ? `clbr-theme-${theme}` : undefined,
-  );
+  const brandAttr = ` data-brand="${brand}"`;
+  const classAttr = "clbr";
   const dirAttr = dir ? ` dir="${dir}"` : "";
   const langAttr = lang ? ` lang="${lang}"` : "";
+  const themeAttr = theme ? ` data-theme="${theme}"` : "";
 
-  return `<div class="${classAttr}"${dirAttr}${langAttr}>${children}</div>`;
+  return `<div class="${classAttr}"${brandAttr}${themeAttr}${langAttr}${dirAttr}>${children}</div>`;
 }
 
 /** Declarative root contract mirror for tooling, docs, and adapters. */
@@ -82,6 +78,17 @@ export const CLBR_ROOT_SPEC = {
   },
   rules: {
     attributes: [
+      {
+        behavior: "always",
+        target: "data-brand",
+        value: "{brand}",
+      },
+      {
+        behavior: "emit",
+        target: "data-theme",
+        value: "{theme}",
+        when: "theme is provided",
+      },
       {
         behavior: "emit",
         target: "dir",
@@ -98,15 +105,6 @@ export const CLBR_ROOT_SPEC = {
         behavior: "always",
         value: "clbr",
       },
-      {
-        behavior: "always",
-        value: "clbr-brand-{brand}",
-      },
-      {
-        behavior: "emit",
-        value: "clbr-theme-{theme}",
-        when: "theme is provided",
-      },
     ],
   },
 } as const;

packages/core/src/components/surface/surface.css

@@ -1,6 +1,6 @@
 @layer clbr.components {
   :where(.clbr) {
-    .clbr-surface {
+    .surface {
       background-color: var(--clbr-color-background-default);
       color: var(--clbr-color-foreground-default);
     }

packages/core/src/components/surface/surface.stories.ts

@@ -5,7 +5,7 @@ const meta = {
     children: {
       control: false,
     },
-    surface: {
+    variant: {
       control: { type: "select" },
       options: ["default", "brand"],
     },
@@ -29,15 +29,15 @@ const exampleContent = `<div style="padding: 1.75rem 1.25rem">Example content</d
 export const Default = {
   args: {
     children: exampleContent,
-    surface: "default",
+    variant: "default",
   },
   render: (args: ClbrSurfaceProps) => renderClbrSurface(args),
 };
 
 export const Brand = {
   args: {
     children: exampleContent,
-    surface: "brand",
+    variant: "brand",
   },
   render: (args: ClbrSurfaceProps) => renderClbrSurface(args),
 };

packages/core/src/components/surface/surface.test.ts

@@ -2,18 +2,19 @@ import { describe, expect, it } from "vitest";
 import { renderClbrSurface } from "./surface";
 
 describe("renderClbrSurface", () => {
-  it("uses only base surface class by default", () => {
+  it("uses base surface class and default variant by default", () => {
     const html = renderClbrSurface({ children: "<p>content</p>" });
-    expect(html).toContain('class="clbr-surface"');
-    expect(html).not.toContain("clbr-surface-default");
+    expect(html).toContain('class="surface"');
+    expect(html).toContain('data-variant="default"');
   });
 
-  it("renders brand surface variant class", () => {
+  it("renders brand surface variant attribute", () => {
     const html = renderClbrSurface({
       children: "<p>content</p>",
-      surface: "brand",
+      variant: "brand",
     });
-    expect(html).toContain('class="clbr-surface clbr-surface-brand"');
+    expect(html).toContain('class="surface"');
+    expect(html).toContain('data-variant="brand"');
   });
 
   it("injects children HTML content", () => {