@carbonid1/design-system 7.3.1 → 7.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,11 @@
1
+ # Adding a semantic color token
2
+
3
+ 1. Define the token in **both** `themes/reader.css` and `themes/dashboard.css`, in both `:root` and `.dark`. Match the existing perceptual color format for uniformity. Light and dark values may use different hue families if the role reads better that way.
4
+ 2. Bridge it in the `@theme inline` block in each theme CSS so Tailwind generates utilities (`--color-my-token: var(--my-token);`).
5
+ 3. Use it via Tailwind classes in components (`bg-my-token`, `text-my-token-foreground`). Opacity modifiers like `bg-my-token/10` work natively on those color variables.
6
+
7
+ Use enough sub-variants for depth — don't squeeze a semantic color into just `base + foreground` when the role needs distinct text/background/border values. Opacity modifiers are a poor substitute for dedicated tokens tuned per role.
8
+
9
+ ## Non-color tokens in a color-sharing namespace
10
+
11
+ A custom `--shadow-*` or `--inset-shadow-*` token shares its utility prefix with colors (`shadow-black/10`), and `cn` classifies any value it doesn't know as a color. Register the name under `extend.theme` in `src/helpers/cn/cn.config.mjs` and add a merge case to `cn.test.ts`; the first test run rebuilds `cn.tables.js`. Namespaces without a color twin, like `font-*` and `animate-*`, merge correctly without this.
@@ -0,0 +1,16 @@
1
+ # Package verification
2
+
3
+ ## Storybook
4
+
5
+ Run these commands from `packages/design-system`:
6
+
7
+ - `pnpm storybook` starts the standalone component browser at `http://localhost:7006`.
8
+ - `pnpm build-storybook` builds the static component documentation.
9
+ - `pnpm test:run:storybook` runs story interaction and accessibility tests through Vitest.
10
+
11
+ ## Verify before you ship
12
+
13
+ - **Stories for everything visual** — `Component.stories.tsx`, one story per visual state, each rendering under both palettes × both modes (the `.storybook/preview.ts` toolbar switchers prove it in isolation before shipping). Story-level `.test()` methods for interaction behavior. **Vitest** for non-visual helpers in `src/helpers/`.
14
+ - **Run the story tests** with `pnpm test:run:storybook` and resolve interaction and accessibility failures before shipping.
15
+ - **UI/UX Pro Max accessibility review** — For any visual, interactive, or token change, invoke the UI/UX Pro Max plugin review lens when available (prefer `ui-ux-pro-max:design-system` for primitives and tokens, `ui-ux-pro-max:ui-styling` for component styling, and `ui-ux-pro-max:ui-ux-pro-max` when unsure) and let it choose the relevant checks for the diff. The review must still cover keyboard navigation, visible focus states, contrast, accessible names/ARIA, screen-reader semantics, responsive behavior, interaction states, and reduced-motion behavior where they apply. In the handoff, name the lens used and summarize findings; for non-visual package housekeeping, say it does not apply. Package rules stay authoritative over broad style suggestions.
16
+ - **Prove it downstream.** The real proof a change works is at least one app or fixture outside the package rendering it; a primitive that type-checks can still look wrong under a palette you never opened.