@lapismd/design-core 0.1.0

package/spec/src/styling-and-themes.md

@@ -0,0 +1,188 @@
+# Styling and themes
+
+Design Core styling is native CSS driven by semantic tokens. Themes and consumers may customize documented tokens without depending on private DOM selectors. Diff surfaces read `--ui-diff-*` defaults from `src/shared/diff/diff.tokens.css`.
+
+## Public surface coverage
+
+| Surface               | Public boundary | Requirement |
+| --------------------- | --------------- | ----------- |
+| Native CSS            | Styling         | DC-CSS-001  |
+| Design tokens         | Styling         | DC-CSS-002  |
+| Theme surfaces        | Theme           | DC-CSS-003  |
+| Accessibility styling | Styling         | DC-CSS-004  |
+| No utility leakage    | Styling         | DC-CSS-005  |
+| Visually hidden text  | Styling         | DC-CSS-006  |
+| Lapis workspace sans  | Theme           | DC-CSS-007  |
+
+## DC-CSS-001 — Native CSS
+
+**Requirement.** The Native CSS family MUST use authored CSS and shared tokens as the production styling contract.
+
+### Acceptance details
+
+- Consumers may override documented semantic tokens without depending on private selectors.
+- Workspace view tokens MUST expose resolved primary and secondary backgrounds so movable views can preserve contrast without placement selectors.
+- Styling validation must distinguish source ownership from Storybook-only presentation.
+
+## DC-CSS-002 — Design tokens
+
+**Requirement.** The Design tokens family MUST provide semantic custom properties for color, spacing, typography, radius, focus, and component-specific extension points.
+
+### Acceptance details
+
+- Consumers may override documented semantic tokens without depending on private selectors.
+- Styling validation must distinguish source ownership from Storybook-only presentation.
+- `src/styles.css` MUST import each shadcn family's `*.tokens.css`, including project-authored families such as `command-view`.
+- `src/styles.css` MUST import the shared workspace desktop drag-region stylesheet so `data-desktop-drag-region` maps to native `app-region` surfaces.
+
+## DC-CSS-003 — Theme surfaces
+
+**Requirement.** The Theme surfaces family MUST apply supported visual themes through documented attributes and shared style entry points.
+
+### Acceptance details
+
+- Consumers may override documented semantic tokens without depending on private selectors.
+- Styling validation must distinguish source ownership from Storybook-only presentation.
+- Compiled palette anchors `--color-white` and `--color-black` MUST be defined on `:root`, not only inside `@theme inline`.
+
+## DC-CSS-004 — Accessibility styling
+
+**Requirement.** The Accessibility styling family MUST retain visible focus, forced-colors, reduced-motion, disabled, invalid, and high-contrast behavior where relevant.
+
+### Acceptance details
+
+- Consumers may override documented semantic tokens without depending on private selectors.
+- Styling validation must distinguish source ownership from Storybook-only presentation.
+
+## DC-CSS-005 — No utility leakage
+
+**Requirement.** The No utility leakage family MUST keep Tailwind utility syntax out of owned production Svelte, TypeScript, and CSS sources.
+
+### Acceptance details
+
+- Consumers may override documented semantic tokens without depending on private selectors.
+- Styling validation must distinguish source ownership from Storybook-only presentation.
+
+## DC-CSS-006 — Visually hidden text
+
+**Requirement.** The public runtime stylesheet MUST hide production `sr-only` content without requiring a consumer Tailwind source scan.
+
+### Acceptance details
+
+- Accessible names must remain available to assistive technology.
+- Linked application builds must not display icon-button labels or hidden dialog headings.
+
+## DC-CSS-007 — Lapis workspace sans
+
+**Requirement.** The Lapis theme MUST bind `--ui-workspace-font-sans` through the brand `--font-sans` stack so AppShell, Settings, explorer, and other workspace chrome share the same sans family as forms.
+
+### Acceptance details
+
+- The token MUST start with `var(--font-sans)` and MAY keep system and emoji fallbacks after that family.
+- Theme contract tests MUST reject a system-ui-only `--ui-workspace-font-sans` stack.
+
+## Styling implementation guide
+
+Layer-specific contracts remain in
+[`Forms and shared UI`](forms/guidance.md),
+[`Shadcn guidance`](../../docs/agent/shadcn.md), and the Storybook Guidance
+pages.
+
+### Principles
+
+1. **Theme first** — global look comes from `src/theme.css`: `--background`,
+   `--primary`, `--border`, `--radius`, and related semantic values.
+2. **Public tokens next** — layers expose overrideable `--ui-*` custom
+   properties. Hosts restyle by setting variables, not by merging utility
+   classes.
+3. **Colocated CSS paints** — component layout and chrome live in sibling CSS,
+   reading tokens through `var(--…)`.
+4. **Semantic hosts** — mark roots with `data-ui-component`, `data-ui-part`,
+   and shadcn `data-slot` or axis attributes. Prefer semantic class names over
+   utility strings.
+5. **Reuse primitives** — use `@lapismd/design-core/shadcn/<family>` for generic
+   buttons, inputs, sheets, and popovers.
+6. **No Tailwind in sources** — retained component sources must not contain
+   utility-class strings, `cn("…")` layout merges, or `tailwind-variants`.
+
+### Token layers
+
+| Layer               | Prefix                         | Defaults                                    |
+| ------------------- | ------------------------------ | ------------------------------------------- |
+| Theme               | `--background`, `--primary`, … | `src/theme.css`                             |
+| Shadcn family       | `--ui-<family>-*`              | `<family>.tokens.css`                       |
+| Forms               | `--ui-form-*`                  | `src/shared/forms/form.tokens.css`          |
+| Filter and AI       | `--ui-*` / `--ui-ai-*`         | colocated CSS and token maps                |
+| Diff                | `--ui-diff-*`                  | `src/shared/diff/diff.tokens.css`           |
+| Structural shell    | `--ui-shell-*`                 | `src/shared/shell/shell.tokens.css`         |
+| Workspace framework | `--ui-workspace-*`             | `src/shared/workspace/workspace.tokens.css` |
+| Desktop drag        | `data-desktop-drag-region`     | `src/shared/workspace/workspace-desktop-drag.css` |
+
+Set public tokens on `:root` or an appropriate shared ancestor such as
+`.ui-structured-form`. Do not rebind a token on the same component host that
+consumes it; that blocks ancestor overrides. Defaults belong on `:root` or the
+layer ancestor, while paint rules read `var(--ui-…, fallback)`.
+
+Shell geometry includes `--ui-shell-mobile-sidebar-width`; its
+`min(22rem, 86cqw)` default follows the bounded shell container rather than the
+global viewport. `--ui-shell-desktop-min-main-width` protects the center stage
+before constrained desktop moves lower-priority sidebars into overlays.
+
+Add a public token only when existing semantic tokens cannot express the
+paint. Document the subset each component reads.
+
+### Component layout
+
+```text
+src/shared/<layer>/<family>/
+  Component.svelte
+  Component.css
+  Component.stories.svelte
+  *.tokens.css / *.tokens.ts
+```
+
+- Drive variants with `data-variant`, `data-density`, and similar attributes.
+- Preserve shadcn `data-ui-component` and `data-slot` attributes when composing
+  families.
+- Style nested primitives from the parent family CSS through semantic
+  selectors.
+- Form-specific chrome may use semantic elements painted with `--ui-form-*`.
+
+Do not add per-call-site utility props such as `bodyClass="px-6 py-5"`. Prefer a
+typed variant or density prop backed by native CSS. Do not copy upstream shadcn
+files by hand to bypass `pnpm ui:add`.
+
+### Stories and docs
+
+Stories may use host Tailwind for demonstration layout; stories and
+`examples/` are excluded from the source gate. Forms Docs pages include their
+colocated CSS file and a token table generated by
+`node scripts/generate-form-docs.mjs`. Shadcn families document
+`--ui-<family>-*` customization in their docs.
+
+### Enforcement
+
+`pnpm check:no-tailwind` scans these retained source roots:
+
+- `src/shared/ai`
+- `src/shared/filter`
+- `src/shared/forms`
+- `src/shared/shadcn`
+- `src/shared/shell`
+- `src/shared/workspace`
+
+The detector is `scripts/lib/no-tailwind-utilities.ts`. `sr-only`,
+`not-sr-only`, and marker `cn-*` classes are allowed.
+
+`data-ui` pairing is covered by `src/lib/data-ui-contract.ts`, and `ui:add`
+refuses leftover utilities after native-CSS conversion.
+
+### Checklist
+
+1. Classify the layer with `pnpm ui guide layers` and
+   [`Component inventory`](component-inventory.md).
+2. Prefer an existing shadcn control for generic UI.
+3. Add or update colocated CSS using public tokens.
+4. Stamp `data-ui-component` and `data-ui-part`.
+5. Document the tokens the component reads.
+6. Run `pnpm check:no-tailwind`, focused story checks, and the repository gate.

package/src/lib/data-ui-contract.ts

@@ -0,0 +1,263 @@
+/**
+ * Static checks for `data-ui-component` / `data-ui-part` pairing.
+ *
+ * Regression class: composition CSS uses same-element selectors like
+ * `[data-ui-component="ai-chat-dock"][data-ui-part="root"]`, but the markup
+ * only sets `data-ui-part` (or puts `data-ui-component` on a shadcn host that
+ * already owns that attribute — overwriting Button/Sidebar/etc. styles).
+ */
+
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  DATA_UI_SHADCN_ALLOWLIST,
+  discoverDataUiHostCatalog,
+  isAllowlistedOverride,
+  type DataUiHostCatalog,
+} from "./data-ui-host-catalog.js";
+
+export type DataUiViolation = {
+  file: string;
+  kind:
+    | "missing-component-on-part"
+    | "host-component-override"
+    | "host-part-override"
+    | "orphan-compound-part";
+  message: string;
+};
+
+export type AnalyzeDataUiOptions = {
+  hostComponents?: Record<string, string>;
+  hostParts?: Record<string, string>;
+  /** When set, matching host overrides are ignored (shadcn intentional restyles). */
+  allowlist?: ReadonlyArray<{
+    file: string;
+    tag: string;
+    component: string;
+  }>;
+};
+
+const dirname = path.dirname(fileURLToPath(import.meta.url));
+const defaultShadcnRoot = path.resolve(dirname, "../shared/shadcn");
+
+let cachedCatalog: DataUiHostCatalog | null = null;
+
+/** Load (and cache) the auto-discovered shadcn host catalog. */
+export function loadDataUiHostCatalog(
+  shadcnRoot = defaultShadcnRoot,
+): DataUiHostCatalog {
+  if (cachedCatalog && shadcnRoot === defaultShadcnRoot) return cachedCatalog;
+  const catalog = discoverDataUiHostCatalog(shadcnRoot);
+  if (shadcnRoot === defaultShadcnRoot) cachedCatalog = catalog;
+  return catalog;
+}
+
+/** @deprecated Prefer loadDataUiHostCatalog(); kept for call-site convenience. */
+export function getDataUiHostComponents(): Record<string, string> {
+  return loadDataUiHostCatalog().components;
+}
+
+/** @deprecated Prefer loadDataUiHostCatalog(); kept for call-site convenience. */
+export function getDataUiHostParts(): Record<string, string> {
+  return loadDataUiHostCatalog().parts;
+}
+
+/**
+ * Fallback host map for analyzer unit fixtures (mirrors critical leaf hosts).
+ * Production scans use {@link loadDataUiHostCatalog}.
+ */
+export const DATA_UI_HOST_COMPONENTS: Record<string, string> = {
+  Button: "button",
+  Label: "label",
+  Switch: "switch",
+  Textarea: "textarea",
+  Input: "input",
+  Separator: "separator",
+  Badge: "badge",
+  Spinner: "spinner",
+  Skeleton: "skeleton",
+  ScrollArea: "scroll-area",
+  "Sidebar.Root": "sidebar",
+  "Sidebar.Header": "sidebar",
+  "Sidebar.Footer": "sidebar",
+  "Sidebar.Content": "sidebar",
+  "Sidebar.Provider": "sidebar",
+  "Tooltip.Content": "tooltip",
+  "DropdownMenu.Content": "dropdown-menu",
+};
+
+/**
+ * Fallback fixed-part map for analyzer unit fixtures.
+ */
+export const DATA_UI_HOST_PARTS: Record<string, string> = {
+  "Tooltip.Content": "tooltip-content",
+  "DropdownMenu.Content": "dropdown-menu-content",
+  "Dialog.Content": "dialog-content",
+  ScrollArea: "scroll-area",
+  Switch: "switch",
+  "Sidebar.Root": "sidebar-root",
+  "Sidebar.Header": "sidebar-header",
+  "Sidebar.Content": "sidebar-content",
+  "Sidebar.Footer": "sidebar-footer",
+  "Sidebar.Provider": "sidebar-provider",
+};
+
+export { DATA_UI_SHADCN_ALLOWLIST };
+
+const COMPOUND_SELECTOR_RE =
+  /\[data-ui-component=(["'])([^"']+)\1\]\[data-ui-part=(["'])([^"']+)\3\]/g;
+
+const OPEN_TAG_RE = /<([A-Za-z][\w.]*)(\s[^>]*?)>/g;
+const ATTR_COMPONENT_RE = /\bdata-ui-component=(["'])([^"']*)\1/;
+const ATTR_COMPONENT_PROP_RE = /\bdataUiComponent=(["'])([^"']*)\1/;
+const ATTR_PART_RE = /\bdata-ui-part=(["'])([^"']*)\1/;
+
+function styleBlocks(source: string): string {
+  return [...source.matchAll(/<style\b[^>]*>([\s\S]*?)<\/style>/gi)]
+    .map((match) => match[1] ?? "")
+    .join("\n");
+}
+
+function templateMarkup(source: string): string {
+  return source
+    .replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, "")
+    .replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, "");
+}
+
+function compoundPairs(
+  styles: string,
+): Array<{ component: string; part: string }> {
+  const pairs: Array<{ component: string; part: string }> = [];
+  for (const match of styles.matchAll(COMPOUND_SELECTOR_RE)) {
+    pairs.push({ component: match[2]!, part: match[4]! });
+  }
+  return pairs;
+}
+
+type MarkupTag = {
+  name: string;
+  component: string | null;
+  part: string | null;
+  raw: string;
+};
+
+function markupTags(markup: string): MarkupTag[] {
+  const tags: MarkupTag[] = [];
+  for (const match of markup.matchAll(OPEN_TAG_RE)) {
+    const name = match[1]!;
+    const attrs = match[2] ?? "";
+    const viaAttr = attrs.match(ATTR_COMPONENT_RE)?.[2] ?? null;
+    const viaProp = attrs.match(ATTR_COMPONENT_PROP_RE)?.[2] ?? null;
+    tags.push({
+      name,
+      component: viaProp ?? viaAttr,
+      part: attrs.match(ATTR_PART_RE)?.[2] ?? null,
+      raw: match[0]!,
+    });
+  }
+  return tags;
+}
+
+export function analyzeSvelteSource(
+  source: string,
+  file = "fixture.svelte",
+  options: AnalyzeDataUiOptions = {},
+): DataUiViolation[] {
+  const hostComponents = options.hostComponents ?? DATA_UI_HOST_COMPONENTS;
+  const hostParts = options.hostParts ?? DATA_UI_HOST_PARTS;
+  const allowlist = options.allowlist;
+
+  const violations: DataUiViolation[] = [];
+  const pairs = compoundPairs(styleBlocks(source));
+  const tags = markupTags(templateMarkup(source));
+
+  const partsByComponent = new Map<string, Set<string>>();
+  for (const { component, part } of pairs) {
+    const set = partsByComponent.get(component) ?? new Set<string>();
+    set.add(part);
+    partsByComponent.set(component, set);
+  }
+
+  for (const [component, parts] of partsByComponent) {
+    for (const part of parts) {
+      const matchingParts = tags.filter((tag) => tag.part === part);
+      if (matchingParts.length === 0) {
+        violations.push({
+          file,
+          kind: "orphan-compound-part",
+          message:
+            `CSS uses same-element selector [data-ui-component="${component}"][data-ui-part="${part}"] ` +
+            `but no template tag sets data-ui-part="${part}"`,
+        });
+        continue;
+      }
+      for (const tag of matchingParts) {
+        if (tag.component !== component) {
+          violations.push({
+            file,
+            kind: "missing-component-on-part",
+            message:
+              `Tag <${tag.name}> has data-ui-part="${part}" but CSS targets ` +
+              `[data-ui-component="${component}"][data-ui-part="${part}"] on the same element. ` +
+              `Either set data-ui-component="${component}" on a native host, or change the CSS to a ` +
+              `descendant selector ([data-ui-component="${component}"] [data-ui-part="${part}"]).` +
+              (tag.component
+                ? ` Found data-ui-component="${tag.component}" instead.`
+                : " data-ui-component is missing."),
+          });
+        }
+      }
+    }
+  }
+
+  for (const tag of tags) {
+    if (!tag.component) continue;
+    const expected = hostComponents[tag.name];
+    if (!expected) continue;
+    if (tag.component !== expected) {
+      if (
+        allowlist &&
+        isAllowlistedOverride(file, tag.name, tag.component, allowlist)
+      ) {
+        continue;
+      }
+      violations.push({
+        file,
+        kind: "host-component-override",
+        message:
+          `<${tag.name}> already sets data-ui-component="${expected}"; do not pass ` +
+          `data-ui-component="${tag.component}" (it overwrites host styles). ` +
+          `Use data-ui-part only and style with a descendant selector, or pass ` +
+          `dataUiComponent only for allowlisted intentional family restyles.`,
+      });
+    }
+  }
+
+  for (const tag of tags) {
+    if (!tag.part) continue;
+    const expectedPart = hostParts[tag.name];
+    if (!expectedPart) continue;
+    if (tag.part !== expectedPart) {
+      if (
+        allowlist &&
+        allowlist.some(
+          (entry) =>
+            (file === entry.file || file.endsWith(entry.file)) &&
+            entry.tag === tag.name,
+        )
+      ) {
+        continue;
+      }
+      violations.push({
+        file,
+        kind: "host-part-override",
+        message:
+          `<${tag.name}> already sets data-ui-part="${expectedPart}"; do not pass ` +
+          `data-ui-part="${tag.part}" (rest props overwrite the host part and drop host CSS, ` +
+          `e.g. tooltip background). Use a side-channel attribute instead.`,
+      });
+    }
+  }
+
+  return violations;
+}