@qpmtx/tokens 0.3.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.
Files changed (27) hide show
  1. package/README.md +124 -0
  2. package/dist/css-var.d.ts +28 -0
  3. package/dist/css-var.d.ts.map +1 -0
  4. package/dist/css-var.js +17 -0
  5. package/dist/groups/colors-and-gradients.d.ts +646 -0
  6. package/dist/groups/colors-and-gradients.d.ts.map +1 -0
  7. package/dist/groups/colors-and-gradients.js +644 -0
  8. package/dist/groups/elevation-and-glow-shadows.d.ts +107 -0
  9. package/dist/groups/elevation-and-glow-shadows.d.ts.map +1 -0
  10. package/dist/groups/elevation-and-glow-shadows.js +105 -0
  11. package/dist/groups/motion-and-zindex.d.ts +137 -0
  12. package/dist/groups/motion-and-zindex.d.ts.map +1 -0
  13. package/dist/groups/motion-and-zindex.js +135 -0
  14. package/dist/groups/radius.d.ts +47 -0
  15. package/dist/groups/radius.d.ts.map +1 -0
  16. package/dist/groups/radius.js +45 -0
  17. package/dist/groups/spacing-and-layout.d.ts +157 -0
  18. package/dist/groups/spacing-and-layout.d.ts.map +1 -0
  19. package/dist/groups/spacing-and-layout.js +155 -0
  20. package/dist/groups/typography.d.ts +402 -0
  21. package/dist/groups/typography.d.ts.map +1 -0
  22. package/dist/groups/typography.js +400 -0
  23. package/dist/index.d.ts +18 -0
  24. package/dist/index.d.ts.map +1 -0
  25. package/dist/index.js +17 -0
  26. package/package.json +34 -0
  27. package/tokens.css +248 -0
package/README.md ADDED
@@ -0,0 +1,124 @@
1
+ # @qpmtx/tokens
2
+
3
+ The QPMatrix design token system - colors, typography, spacing, radius,
4
+ elevation/glow shadows, motion, and z-index - transcribed verbatim from the
5
+ owner's design source (`QPMatrix Design System.html`). This package is
6
+ framework-agnostic: no React, no MUI, no styling runtime. It ships two
7
+ aligned deliverables generated from the same 246-token source so they can
8
+ never drift apart:
9
+
10
+ - CSS custom properties - `tokens.css`, importable via `@qpmtx/tokens/css`
11
+ - Typed token objects - const-asserted TS objects, importable via `@qpmtx/tokens`
12
+
13
+ The MUI theme factory that consumes these tokens lives in `@qpmtx/ui`
14
+ (QPM-38), not here - this package only owns the token values themselves.
15
+
16
+ ## Install
17
+
18
+ Within the monorepo, add it as a workspace dependency:
19
+
20
+ ```jsonc
21
+ // apps/*/package.json
22
+ {
23
+ "dependencies": {
24
+ "@qpmtx/tokens": "workspace:*",
25
+ },
26
+ }
27
+ ```
28
+
29
+ ## CSS usage
30
+
31
+ Import the stylesheet once, at the app root (before any component styles):
32
+
33
+ ```ts
34
+ import "@qpmtx/tokens/css";
35
+ ```
36
+
37
+ This defines every `--var` on `:root` (dark theme, the default - QPMatrix's
38
+ primary brand expression) plus a `[data-theme="light"]` override block for
39
+ the subset of semantic tokens that change in light mode. Toggle themes by
40
+ setting `data-theme="light"` (or removing it to fall back to dark) on `<html>`
41
+ or any ancestor element:
42
+
43
+ ```tsx
44
+ <html data-theme={theme === "light" ? "light" : undefined}>
45
+ ```
46
+
47
+ The stylesheet also ships the `qp-*` keyframes (`qp-pulse`, `qp-halo`,
48
+ `qp-flow`, `qp-sweep`, `qp-breathe`, `qp-orbit`, `qp-rise`, `qp-shimmer`,
49
+ `qp-scan`), five ready-to-use `.qp-anim-*` utility classes, and a
50
+ `prefers-reduced-motion: reduce` guard that clamps all animation/transition
51
+ durations to near-zero - respected automatically, no opt-in required.
52
+
53
+ ```css
54
+ .badge {
55
+ color: var(--fg-primary);
56
+ background: var(--surface-primary);
57
+ border: 1px solid var(--border-subtle);
58
+ border-radius: var(--radius-md);
59
+ }
60
+ ```
61
+
62
+ ## TypeScript usage
63
+
64
+ Reference tokens by name instead of hardcoding CSS strings, so a renamed or
65
+ removed token becomes a type error:
66
+
67
+ ```ts
68
+ import { cssVar, colorsAndGradients, radius } from "@qpmtx/tokens";
69
+
70
+ const style = {
71
+ color: cssVar("fg-primary"),
72
+ borderRadius: cssVar("radius-md"),
73
+ };
74
+
75
+ colorsAndGradients["brand-primary"].resolved;
76
+ colorsAndGradients["brand-primary"].light?.resolved;
77
+ radius["radius-md"].resolved;
78
+ ```
79
+
80
+ Every token entry has the shape:
81
+
82
+ ```ts
83
+ {
84
+ raw: string;
85
+ resolved: string;
86
+ light?: { raw: string; resolved: string };
87
+ usedByComponentBundle: boolean;
88
+ }
89
+ ```
90
+
91
+ Six named exports mirror the source's semantic grouping exactly:
92
+
93
+ | Export | Group | Count |
94
+ | ------------------------- | -------------------------- | ------------------------------ |
95
+ | `colorsAndGradients` | colors-and-gradients | 93 (41 have `light` overrides) |
96
+ | `typography` | typography | 77 |
97
+ | `spacingAndLayout` | spacing-and-layout | 28 |
98
+ | `radius` | radius | 6 |
99
+ | `elevationAndGlowShadows` | elevation-and-glow-shadows | 18 |
100
+ | `motionAndZIndex` | motion-and-zindex | 24 |
101
+
102
+ Only `colorsAndGradients` has theme-aware (`light`) entries - typography,
103
+ spacing, radius, elevation, and motion tokens are theme-invariant by design.
104
+
105
+ ## Dark/light theming model
106
+
107
+ Dark is the default `:root` expression and QPMatrix's primary brand surface.
108
+ `[data-theme="light"]` overrides only the 41 semantic color tokens that need
109
+ to change for light mode (backgrounds, surfaces, foregrounds, borders, brand,
110
+ signal, and status colors) - raw palette ramps, typography, spacing, radius,
111
+ elevation shape, and motion timing do not change between themes.
112
+
113
+ ## Extending the token system
114
+
115
+ Never hand-transcribe a new hex/px value from a mockup. See
116
+ `packages/.agents/skills/tokens/SKILL.md` for the read-live-source-first rule
117
+ and the exact steps to add a token (CSS + TS + test together).
118
+
119
+ ## Validation
120
+
121
+ ```sh
122
+ bun test packages/tokens
123
+ bun run --filter @qpmtx/tokens build
124
+ ```
package/dist/css-var.d.ts ADDED
@@ -0,0 +1,28 @@
1
+ import type { ColorsAndGradientsVarName } from "./groups/colors-and-gradients";
2
+ import type { ElevationAndGlowShadowsVarName } from "./groups/elevation-and-glow-shadows";
3
+ import type { MotionAndZIndexVarName } from "./groups/motion-and-zindex";
4
+ import type { RadiusVarName } from "./groups/radius";
5
+ import type { SpacingAndLayoutVarName } from "./groups/spacing-and-layout";
6
+ import type { TypographyVarName } from "./groups/typography";
7
+ /**
8
+ * Union of every CSS custom-property name (without the leading `--`) shipped
9
+ * by @qpmtx/tokens. Kept in sync with the token group objects — see
10
+ * packages/.agents/skills/tokens/SKILL.md for how to add a token.
11
+ */
12
+ export type TokenVarName = ColorsAndGradientsVarName | TypographyVarName | SpacingAndLayoutVarName | RadiusVarName | ElevationAndGlowShadowsVarName | MotionAndZIndexVarName;
13
+ /**
14
+ * Build a `var(--token-name)` reference for a known QPMatrix design token.
15
+ *
16
+ * Consumers use this instead of hardcoding `"var(--brand-primary)"` strings,
17
+ * so a renamed or removed token becomes a type error rather than a silent
18
+ * runtime mismatch.
19
+ *
20
+ * @example
21
+ * ```ts
22
+ * import { cssVar } from "@qpmtx/tokens";
23
+ *
24
+ * const style = { color: cssVar("fg-primary") }; // -> { color: "var(--fg-primary)" }
25
+ * ```
26
+ */
27
+ export declare function cssVar(name: TokenVarName): string;
28
+ //# sourceMappingURL=css-var.d.ts.map
package/dist/css-var.d.ts.map ADDED
@@ -0,0 +1 @@
1
+ {"version":3,"file":"css-var.d.ts","sourceRoot":"","sources":["../src/css-var.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,+BAA+B,CAAC;AAC/E,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,qCAAqC,CAAC;AAC1F,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AACzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AAC3E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAE7D;;;;GAIG;AACH,MAAM,MAAM,YAAY,GACpB,yBAAyB,GACzB,iBAAiB,GACjB,uBAAuB,GACvB,aAAa,GACb,8BAA8B,GAC9B,sBAAsB,CAAC;AAE3B;;;;;;;;;;;;;GAaG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAEjD"}
package/dist/css-var.js ADDED
@@ -0,0 +1,17 @@
1
+ /**
2
+ * Build a `var(--token-name)` reference for a known QPMatrix design token.
3
+ *
4
+ * Consumers use this instead of hardcoding `"var(--brand-primary)"` strings,
5
+ * so a renamed or removed token becomes a type error rather than a silent
6
+ * runtime mismatch.
7
+ *
8
+ * @example
9
+ * ```ts
10
+ * import { cssVar } from "@qpmtx/tokens";
11
+ *
12
+ * const style = { color: cssVar("fg-primary") }; // -> { color: "var(--fg-primary)" }
13
+ * ```
14
+ */
15
+ export function cssVar(name) {
16
+ return `var(--${name})`;
17
+ }