@kazamitte/design-token 0.0.0-stage → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kazamitte
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,281 @@
-# Temporary Holding Version
+# @kazamitte/design-token
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A design token layer for Tailwind CSS v4 — color, typography, and style themes. Requires Tailwind v4.
+
+Every color token clears WCAG AA for normal text. No single scale can do that across every hue, so the steps differ from color to color.
+
+## Setup
+
+Install the package alongside Tailwind CSS v4, which it expects as a peer dependency.
+
+```sh
+npm install @kazamitte/design-token tailwindcss
+```
+
+### CSS
+
+Import Tailwind first, then the package. The package does not import Tailwind itself, so it is loaded once and you keep control over how it is imported.
+
+```css
+@import "tailwindcss";
+
+@import "@kazamitte/design-token/index.css";
+@import "@kazamitte/design-token/theme/color/default.css";
+@import "@kazamitte/design-token/theme/style/soft.css";
+
+@source '../node_modules/@kazamitte/design-token';
+
+body {
+  background-color: var(--r-base-bg);
+  color: var(--r-base-fg);
+}
+```
+
+The `@source` directive is required because Tailwind v4 excludes `node_modules` from scanning by default. See [Detecting classes in source files](https://tailwindcss.com/docs/detecting-classes-in-source-files) in the Tailwind docs.
+
+### JavaScript
+
+The JavaScript API exposes one function, for generating a color theme.
+
+```ts
+import { generateColorTheme } from "@kazamitte/design-token";
+```
+
+Everything the package does is delivered as CSS, so the JavaScript API is optional. Reach for it to generate several themes at once, or to swap themes at runtime from the app. See [Color theme generation](./docs/generate-color-theme.md) for usage.
+
+### Further reading
+
+- [Color theme generation](./docs/generate-color-theme.md) — writing a theme file with `generateColorTheme`
+- [Color pairings](./docs/color-pairings.md) — which secondary, base and link colors suit each primary (Japanese)
+- [Fixing class conflicts with tailwind-merge](./docs/tailwind-merge.md) — registering the package's utilities with tailwind-merge
+
+---
+
+## Layout
+
+```text
+tailwind/
+├─ base/
+│  ├─ initialize.css       clears the Tailwind color / font / text namespaces
+│  ├─ color/
+│  │  ├─ palette.css       the raw palette (every --color-*)
+│  │  ├─ semantic.css      --c-<hue>-*, 26 hues x 15 tokens, light/dark
+│  │  ├─ status.css        error / warning / success / info
+│  │  └─ utility.css       role utilities (primary-bg, base-fg, …)
+│  ├─ typography/
+│  │  ├─ font.css
+│  │  └─ utility.css
+│  └─ style/
+│     ├─ animation.css     the keyframes and the --animate-* steps on them
+│     ├─ radius.css        the radius scale
+│     ├─ shadow.css        the shadow scale and the colors it is built from
+│     └─ z-index.css       the layering scale
+├─ theme/
+│  ├─ color/               base / primary / secondary / link
+│  └─ style/               neutral / editorial / soft / dense
+└─ index.css               loads the base, the dark variant, duration utilities
+```
+
+## Color
+
+### Roles
+
+- Theme colors
+  - primary
+  - secondary
+  - base
+  - link
+- Status colors
+  - error — red
+  - warning — amber
+  - success — green
+  - info — blue
+
+Each role carries 15 tokens.
+
+| Group      | Tokens                                                                       |
+| ---------- | ---------------------------------------------------------------------------- |
+| Text       | `fg-strong`, `fg`, `fg-muted`, `fg-subtle`                                   |
+| Background | `bg`, `bg-subtle`, `bg-muted`, `bg-selected`, `bg-solid`                     |
+| Border     | `border-subtle`, `border-muted`, `border-selected`, `border`, `border-solid` |
+| Contrast   | `fg-contrast`                                                                |
+| Focus ring | `focus-ring`                                                                 |
+
+### Pairs that clear the contrast requirement
+
+These four clear the WCAG AA threshold for normal text (4.5:1) across all 26 hues, in both light and dark.
+
+- `fg-strong` on `bg-selected` — emphasized text on a hover surface
+- `fg` on `bg-muted` — body text on a selected surface
+- `fg-muted` on `bg` — secondary text on a tinted surface
+- `fg-contrast` on `bg-solid` — the label on a filled control
+
+`fg-subtle` is exempt from the requirement: it is meant for decoration and disabled states.
+
+Roles can take different hues, so text from one role often sits on a surface from another — base text on a primary surface, or a link on a base surface. These clear 4.5:1 for text from any hue on a surface from any other hue, in both light and dark.
+
+- `fg-strong` on `bg`, `bg-subtle` or `bg-muted`
+- `fg` on `bg` or `bg-subtle`
+- `fg-muted` on `bg`
+- `fg-contrast` on `bg-solid`
+
+For links, `link-fg` is the `fg-muted` of the link hue and `link-fg-strong` is its `fg`, so a link on any `bg` clears, and `link-fg-strong` also clears on `bg-subtle`.
+
+One exception: in dark, indigo `fg` on a yellow or lime `bg-subtle` falls to about 4.3:1.
+
+For non-text contrast (WCAG 1.4.11, 3:1), `border-solid`, `bg-solid` and `focus-ring` share a step and stand out from `bg` and `bg-subtle` of any hue, and from `bg-muted` of the same hue or of a neutral. Use them for input borders, checkboxes, progress bars, focus indicators and the like. A focus ring drawn against a solid control matches its fill, so separate the two with an offset in a `bg` color.
+
+In dark, `bg-solid` is a light fill and `fg-contrast` a dark label. No fill dark enough for a white label also stands out 3:1 from a dark surface.
+
+`fg-subtle` is not held to 3:1.
+
+### Choosing a border
+
+- `border` is the default frame for containers: cards, lists, tables, code blocks, popovers, menus and toasts. It is decorative, about 2.5:1 against `bg`, and is not held to 3:1.
+- `border-solid` is for controls that need 3:1 under WCAG 1.4.11, such as inputs and checkboxes.
+- `border-subtle` and `border-muted` are for faint dividers.
+- `border-selected` marks a selected state.
+
+The steps run `border-subtle` < `border-muted` < `border-selected` < `border` < `border-solid` in strength, in every hue and both modes.
+
+Contrast is measured the way axe-core measures it: out-of-gamut colors are clipped to sRGB, nothing is rounded, and a pair passes only when its ratio is strictly greater than the threshold.
+
+### Semantic tokens
+
+All 26 hues expose the same 15 tokens under `--c-*`. Use them where a specific color is wanted directly — tags, categories, charts.
+
+```html
+<span class="bg-(--c-lime-bg-subtle) text-(--c-lime-fg)">Draft</span>
+```
+
+### Palette
+
+Adjusted from the Tailwind 4.3.0 default theme. All 26 hues are defined, including mauve, olive, mist and taupe, which Tailwind added in 4.2.
+
+Every hue also carries two steps Tailwind does not have — 350 and 750 — each the OKLCH midpoint of its neighbours. They let a semantic token sit between two Tailwind steps where neither one holds the contrast requirement across hues.
+
+## Typography
+
+Modeled on [digital-go-jp/tailwind-theme-plugin](https://github.com/digital-go-jp/tailwind-theme-plugin).
+
+Each utility sets font-size, line-height and letter-spacing together.
+
+```html
+<h1 class="text-display-48">…</h1>
+<p class="text-body-16">…</p>
+```
+
+| Utility            | Variants                  | Use              |
+| ------------------ | ------------------------- | ---------------- |
+| `text-display-*`   | 64, 56, 48, 44            | Hero, page title |
+| `text-highlight-*` | 36, 32, 28, 26, 24, 22    | Headings         |
+| `text-body-*`      | 20, 18, 16                | Body copy        |
+| `text-dense-*`     | 18, 16, 14 (+ `-compact`) | Tables, dense UI |
+| `text-oneline-*`   | 18, 16, 14                | Labels, buttons  |
+| `text-mono-*`      | 18, 16, 14                | Code             |
+
+## Style
+
+A style preset sets spacing, radius, shadow, duration and easing together, so that the whole interface reads as one.
+
+| Preset      | Character                                                              |
+| ----------- | ---------------------------------------------------------------------- |
+| `neutral`   | A balanced default                                                     |
+| `editorial` | Sharp corners and the shallowest shadows; hierarchy comes from borders |
+| `soft`      | Generous rounding and pronounced elevation                             |
+| `dense`     | Minimal rounding and elevation, for information-dense UI               |
+
+```html
+<div class="rounded-surface shadow-raised hover:shadow-raised-hover"></div>
+```
+
+Radius and easing do not name their utilities after the `@theme` namespace they live in: `--radius-*` generates `rounded-*`, and `--ease-*` generates `ease-*`.
+
+`--spacing` is the base step of the spacing scale and has no utility of its own. `p-4` is emitted as `calc(var(--spacing) * 4)`, so switching preset moves `p-*`, `m-*`, `gap-*`, `size-*` and the rest together — note that the sizing utilities read the same variable.
+
+| Utility         | Variants                                       | Sets                         |
+| --------------- | ---------------------------------------------- | ---------------------------- |
+| `p-*` `gap-*` … | every utility reads `--spacing`, the base step | spacing and sizing           |
+| `rounded-*`     | tight, control, surface, overlay, pill         | `border-radius`              |
+| `shadow-*`      | flat, raised, floating (+ `-hover`), overlay   | `box-shadow`                 |
+| `duration-*`    | instant, transition, enter                     | `transition-duration`        |
+| `ease-*`        | standard, emphasized                           | `transition-timing-function` |
+| `animate-*`     | fade / scale / slide, in and out               | `animation`                  |
+
+Every duration collapses to 1ms under `prefers-reduced-motion: reduce`.
+
+### Motion
+
+`animate-*` covers the enter and exit of the things that appear over the page.
+
+| Utility                     | Use                      |
+| --------------------------- | ------------------------ |
+| `animate-fade-in` / `-out`  | Scrims, tab panels       |
+| `animate-scale-in` / `-out` | Dialogs, menus, popovers |
+| `animate-slide-in-from-*`   | Drawers, sheets, toasts  |
+| `animate-slide-out-to-*`    | The same, leaving        |
+
+The slide steps take `top`, `right`, `bottom` and `left`, and travel the full
+size of the element unless it says otherwise.
+
+```html
+<div class="animate-slide-in-from-bottom [--slide-distance:1rem]"></div>
+```
+
+Every step is composed from the preset's duration and easing, so it follows the
+preset and collapses to 1ms under reduced motion. Tailwind's own `animate-spin`,
+`-ping`, `-pulse` and `-bounce` are untouched and keep animating under reduced
+motion.
+
+Exit animations only play while the element is still in the tree; unmount it on
+`animationend`.
+
+Collapse and expand are not included. They need a measured height, which no
+keyframe can supply.
+
+### Layering
+
+`z-*` follows [Chakra UI's z-index scale](https://chakra-ui.com/docs/theming/z-index), so the order matches what component libraries assume — notably `popover` above `modal`, since a select opened inside a dialog has to clear it.
+
+| Step       | Value | Step       | Value      |
+| ---------- | ----- | ---------- | ---------- |
+| `hide`     | -1    | `overlay`  | 1300       |
+| `base`     | 0     | `modal`    | 1400       |
+| `docked`   | 10    | `popover`  | 1500       |
+| `dropdown` | 1000  | `skip-nav` | 1600       |
+| `sticky`   | 1100  | `toast`    | 1700       |
+| `banner`   | 1200  | `tooltip`  | 1800       |
+|            |       | `max`      | 2147483647 |
+
+Layering does not vary by preset, so these are used directly rather than through
+one. `z-10` and `z-auto` still work alongside them. `<dialog>` and the Popover
+API render in the top layer, where z-index has no effect.
+
+### Shadow
+
+`--shadow-2xs` through `--shadow-2xl` are the base scale, seven steps. A preset picks one step per role and does nothing more; light and dark are resolved inside the scale, so no preset carries a dark override.
+
+Each step reads its colors through the custom properties below. These four are all that `[data-mode='dark']` swaps.
+
+| Custom property         | Light     | Dark      |
+| ----------------------- | --------- | --------- |
+| `--shadow-color-subtle` | black 5%  | black 35% |
+| `--shadow-color`        | black 10% | black 50% |
+| `--shadow-color-strong` | black 25% | black 70% |
+| `--shadow-rim-color`    | black 7%  | white 12% |
+
+A cast shadow barely reads on a dark surface, so every step opens with a `0 0 0 1px var(--shadow-rim-color)` rim. In dark it is that white rim that separates a surface from its background, while the heavier cast carries the elevation. `--shadow-2xs` is the rim alone — an edge with no elevation.
+
+To recolor the shadows, redefine those four under `:root` and `[data-mode='dark']`; the whole scale, and every preset built on it, follows.
+
+---
+
+## AI assistance
+
+The documentation and code in this package were written with AI agents — Claude and ChatGPT. Every output was reviewed by a human before it was committed.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).
+
+The color palette comes from Tailwind CSS and the typography scale from digital-go-jp/tailwind-theme-plugin, both MIT. Their notices are reproduced in [THIRD-PARTY-NOTICES.md](./THIRD-PARTY-NOTICES.md).

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,69 @@
+# Third-party notices
+
+This package contains material derived from the projects below. Both are
+distributed under the MIT License, which requires its copyright notice to
+travel with any substantial portion of the work. The notices are reproduced
+here in full.
+
+## Tailwind CSS
+
+`tailwind/base/color/palette.css` holds the 286 color values of the Tailwind
+CSS v4.3 default theme. Those colors are unchanged; only the hue component of
+the achromatic steps is written as `0` rather than `none`.
+
+The same file adds 52 colors that are not in Tailwind: a 350 and a 750 step
+for each of the 26 hues, each the OKLCH midpoint of the two Tailwind steps
+around it. They are derived from the Tailwind values above.
+
+Tailwind CSS is also the framework this package extends.
+
+> MIT License
+>
+> Copyright (c) Tailwind Labs, Inc.
+>
+> Permission is hereby granted, free of charge, to any person obtaining a copy
+> of this software and associated documentation files (the "Software"), to deal
+> in the Software without restriction, including without limitation the rights
+> to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+> copies of the Software, and to permit persons to whom the Software is
+> furnished to do so, subject to the following conditions:
+>
+> The above copyright notice and this permission notice shall be included in
+> all copies or substantial portions of the Software.
+>
+> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+> FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+> AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+> LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+> OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+> SOFTWARE.
+
+## digital-go-jp/tailwind-theme-plugin
+
+The typography scale in `tailwind/base/typography/utility.css` follows the
+Digital Agency Design System as published through that plugin. The utilities
+are written from scratch for Tailwind v4; the font sizes, line heights and
+letter spacings come from the plugin's scale.
+
+> MIT License
+>
+> Copyright (c) 2023 デジタル庁
+>
+> Permission is hereby granted, free of charge, to any person obtaining a copy
+> of this software and associated documentation files (the "Software"), to deal
+> in the Software without restriction, including without limitation the rights
+> to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+> copies of the Software, and to permit persons to whom the Software is
+> furnished to do so, subject to the following conditions:
+>
+> The above copyright notice and this permission notice shall be included in
+> all copies or substantial portions of the Software.
+>
+> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+> FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+> AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+> LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+> OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+> SOFTWARE.

package/dist/generate-theme.d.mts

@@ -0,0 +1,25 @@
+export type ChromaticColor =
+  | 'red' | 'orange' | 'amber' | 'yellow' | 'lime'
+  | 'green' | 'emerald' | 'teal' | 'cyan' | 'sky'
+  | 'blue' | 'indigo' | 'violet' | 'purple' | 'fuchsia'
+  | 'pink' | 'rose';
+
+export type BaseColor =
+  | 'slate' | 'gray' | 'zinc' | 'neutral' | 'stone'
+  | 'mauve' | 'olive' | 'mist' | 'taupe';
+
+export type Palette = ChromaticColor | BaseColor;
+
+export interface ColorTheme {
+  base: Palette;
+  primary: Palette;
+  secondary: Palette;
+  link: Palette;
+}
+
+/**
+ * Generates the contents of a color theme stylesheet.
+ *
+ * Returns CSS as a string.
+ */
+export declare const generateColorTheme: (theme: ColorTheme) => string;

package/dist/generate-theme.mjs

@@ -0,0 +1,61 @@
+// indent width: 2 half-width spaces
+const INDENT = " ".repeat(2);
+
+/**
+ * Role token names.
+ *
+ * These mirror the `--r-<role>-*` custom properties that
+ * `theme/color/default.css` defines and `base/color/utility.css`
+ * consumes, so generated themes are drop-in replacements for it.
+ */
+const ROLE_TOKENS = [
+  "bg",
+  "bg-subtle",
+  "bg-muted",
+  "bg-selected",
+  "bg-solid",
+  "border-subtle",
+  "border-muted",
+  "border-selected",
+  "border",
+  "border-solid",
+  "fg-strong",
+  "fg",
+  "fg-muted",
+  "fg-subtle",
+  "fg-contrast",
+  "focus-ring",
+];
+
+const roleBlock = (role, color) => {
+  const lines = ROLE_TOKENS.map(
+    (t) => `${INDENT}--r-${role}-${t}: var(--c-${color}-${t});`,
+  );
+  return lines.join("\n");
+};
+
+const linkBlock = (color) =>
+  [
+    `${INDENT}--r-link-fg: var(--c-${color}-fg-muted);`,
+    `${INDENT}--r-link-fg-strong: var(--c-${color}-fg);`,
+  ].join("\n");
+
+/** Generates the contents of a color theme stylesheet. */
+export const generateColorTheme = (theme) => {
+  const { base, primary, secondary, link } = theme;
+
+  return `:root {
+${INDENT}/* base - ${base} */
+${roleBlock("base", base)}
+
+${INDENT}/* primary - ${primary} */
+${roleBlock("primary", primary)}
+
+${INDENT}/* secondary - ${secondary} */
+${roleBlock("secondary", secondary)}
+
+${INDENT}/* link - ${link} */
+${linkBlock(link)}
+}
+`;
+};