@code-sherpas/pharos-tokens 0.8.0 → 1.0.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.
package/README.md CHANGED
@@ -73,7 +73,7 @@ import colorDtcg from '@code-sherpas/pharos-tokens/dtcg/color';
73
73
 
74
74
  ## Rules for consumers
75
75
 
76
- See [RULES.md](./RULES.md) — published with the package.
76
+ See [the rules for consumers](https://app.notion.com/p/4071751eee1081b2b000e212c80761b4) in Notion (Programa Pharos), where Pharos keeps its documentation (decision D27).
77
77
 
78
78
  ## Token structure
79
79
 
package/dist/index.js CHANGED
@@ -122,17 +122,6 @@ export const tokens = {
122
122
  "toast": "1700",
123
123
  "tooltip": "1800"
124
124
  },
125
- "z": {
126
- "0": "0",
127
- "header": "1000",
128
- "above-header": "1100",
129
- "modal-overlay": "9998",
130
- "modal": "9999",
131
- "drawer-overlay": "9999",
132
- "drawer": "10000",
133
- "dropdown": "10001",
134
- "tooltip": "10002"
135
- },
136
125
  "duration": {
137
126
  "fast": "100ms",
138
127
  "normal": "200ms",
@@ -230,13 +219,6 @@ export const tokens = {
230
219
  "lineHeight": "1.25",
231
220
  "letterSpacing": "0"
232
221
  },
233
- "lesson-title": {
234
- "fontFamily": "\"Outfit\", Inter, system-ui, -apple-system, \"Segoe UI\", Roboto, \"Helvetica Neue\", Arial, sans-serif",
235
- "fontSize": "1.25rem",
236
- "fontWeight": "600",
237
- "lineHeight": "1.25",
238
- "letterSpacing": "0"
239
- },
240
222
  "subtitle": {
241
223
  "fontFamily": "\"Outfit\", Inter, system-ui, -apple-system, \"Segoe UI\", Roboto, \"Helvetica Neue\", Arial, sans-serif",
242
224
  "fontSize": "1.125rem",
package/dist/styles.css CHANGED
@@ -71,18 +71,9 @@
71
71
  --pharos-z-index-popover: 1500; /** Anchored floating UI: Popover, DropdownMenu, Select and Combobox lists. Above modal so it can open from inside a Dialog or Sheet. */
72
72
  --pharos-z-index-toast: 1700; /** Toasts and transient notifications. */
73
73
  --pharos-z-index-tooltip: 1800; /** Tooltips: always on top. */
74
- --pharos-z-0: 0; /** DEPRECATED: use --pharos-z-index-base (decision D29). Removed in the next major. */
75
- --pharos-z-header: 1000; /** DEPRECATED: use --pharos-z-index-sticky (decision D29). Removed in the next major. */
76
- --pharos-z-above-header: 1100; /** DEPRECATED: use --pharos-z-index-sticky (decision D29). Removed in the next major. */
77
- --pharos-z-modal-overlay: 9998; /** DEPRECATED: use --pharos-z-index-overlay (decision D29). Removed in the next major. */
78
- --pharos-z-modal: 9999; /** DEPRECATED: use --pharos-z-index-modal (decision D29). Removed in the next major. */
79
- --pharos-z-drawer-overlay: 9999; /** DEPRECATED: use --pharos-z-index-overlay (decision D29). Removed in the next major. */
80
- --pharos-z-drawer: 10000; /** DEPRECATED: use --pharos-z-index-modal (decision D29). Removed in the next major. */
81
- --pharos-z-dropdown: 10001; /** DEPRECATED: use --pharos-z-index-popover (decision D29). Removed in the next major. */
82
- --pharos-z-tooltip: 10002; /** DEPRECATED: use --pharos-z-index-tooltip (decision D29). Removed in the next major. */
83
- --pharos-duration-fast: 100ms; /** Micro interactions (hover). */
84
- --pharos-duration-normal: 200ms; /** Default transitions. */
85
- --pharos-duration-slow: 300ms; /** Panel slide, overlay fade. */
74
+ --pharos-duration-fast: 0.1s; /** Micro interactions (hover). */
75
+ --pharos-duration-normal: 0.2s; /** Default transitions. */
76
+ --pharos-duration-slow: 0.3s; /** Panel slide, overlay fade. */
86
77
  --pharos-easing-in: cubic-bezier(0.4, 0, 1, 1);
87
78
  --pharos-easing-out: cubic-bezier(0, 0, 0.2, 1);
88
79
  --pharos-easing-in-out: cubic-bezier(0.4, 0, 0.2, 1);
@@ -103,7 +94,7 @@
103
94
  --pharos-spacing-0-5: 0.125rem; /** 2px step of the rem scale. */
104
95
  --pharos-spacing-1-5: 0.375rem; /** 6px step of the rem scale. */
105
96
  --pharos-spacing-2-5: 0.625rem; /** 10px step of the rem scale. */
106
- --pharos-font-family-sans: "Outfit", Inter, system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif; /** Default sans-serif stack. Outfit is the primary face (Decision D8); Inter is the fallback before system fonts. Loading Outfit is the consumer's responsibility — see RULES.md §8. */
97
+ --pharos-font-family-sans: "Outfit", Inter, system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif; /** Default sans-serif stack. Outfit is the primary face (Decision D8); Inter is the fallback before system fonts. Loading Outfit is the consumer's responsibility — rule 8 of the consumer rules linked from the README. */
107
98
  --pharos-font-family-mono: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace; /** Default monospace stack for code. */
108
99
  --pharos-font-weight-regular: 400;
109
100
  --pharos-font-weight-medium: 500;
@@ -164,11 +155,6 @@
164
155
  --pharos-type-h4-font-weight: var(--pharos-font-weight-semibold); /** H4 (xl). */
165
156
  --pharos-type-h4-line-height: var(--pharos-font-line-height-tight); /** H4 (xl). */
166
157
  --pharos-type-h4-letter-spacing: var(--pharos-font-letter-spacing-normal); /** H4 (xl). */
167
- --pharos-type-lesson-title-font-family: var(--pharos-font-family-sans); /** DEPRECATED: use --pharos-type-h4. Removed in the next major. */
168
- --pharos-type-lesson-title-font-size: var(--pharos-font-size-xl); /** DEPRECATED: use --pharos-type-h4. Removed in the next major. */
169
- --pharos-type-lesson-title-font-weight: var(--pharos-font-weight-semibold); /** DEPRECATED: use --pharos-type-h4. Removed in the next major. */
170
- --pharos-type-lesson-title-line-height: var(--pharos-font-line-height-tight); /** DEPRECATED: use --pharos-type-h4. Removed in the next major. */
171
- --pharos-type-lesson-title-letter-spacing: var(--pharos-font-letter-spacing-normal); /** DEPRECATED: use --pharos-type-h4. Removed in the next major. */
172
158
  --pharos-type-subtitle-font-family: var(--pharos-font-family-sans); /** Subtitles (lg). */
173
159
  --pharos-type-subtitle-font-size: var(--pharos-font-size-lg); /** Subtitles (lg). */
174
160
  --pharos-type-subtitle-font-weight: var(--pharos-font-weight-medium); /** Subtitles (lg). */
package/dist/tokens.d.ts CHANGED
@@ -162,24 +162,6 @@ export const PharosZIndexPopover: string;
162
162
  export const PharosZIndexToast: string;
163
163
  /** Tooltips: always on top. */
164
164
  export const PharosZIndexTooltip: string;
165
- /** DEPRECATED: use --pharos-z-index-base (decision D29). Removed in the next major. */
166
- export const PharosZ0: string;
167
- /** DEPRECATED: use --pharos-z-index-sticky (decision D29). Removed in the next major. */
168
- export const PharosZHeader: string;
169
- /** DEPRECATED: use --pharos-z-index-sticky (decision D29). Removed in the next major. */
170
- export const PharosZAboveHeader: string;
171
- /** DEPRECATED: use --pharos-z-index-overlay (decision D29). Removed in the next major. */
172
- export const PharosZModalOverlay: string;
173
- /** DEPRECATED: use --pharos-z-index-modal (decision D29). Removed in the next major. */
174
- export const PharosZModal: string;
175
- /** DEPRECATED: use --pharos-z-index-overlay (decision D29). Removed in the next major. */
176
- export const PharosZDrawerOverlay: string;
177
- /** DEPRECATED: use --pharos-z-index-modal (decision D29). Removed in the next major. */
178
- export const PharosZDrawer: string;
179
- /** DEPRECATED: use --pharos-z-index-popover (decision D29). Removed in the next major. */
180
- export const PharosZDropdown: string;
181
- /** DEPRECATED: use --pharos-z-index-tooltip (decision D29). Removed in the next major. */
182
- export const PharosZTooltip: string;
183
165
  /** Micro interactions (hover). */
184
166
  export const PharosDurationFast: string;
185
167
  /** Default transitions. */
@@ -223,7 +205,7 @@ export const PharosSpacing05: string;
223
205
  export const PharosSpacing15: string;
224
206
  /** 10px step of the rem scale. */
225
207
  export const PharosSpacing25: string;
226
- /** Default sans-serif stack. Outfit is the primary face (Decision D8); Inter is the fallback before system fonts. Loading Outfit is the consumer's responsibility — see RULES.md §8. */
208
+ /** Default sans-serif stack. Outfit is the primary face (Decision D8); Inter is the fallback before system fonts. Loading Outfit is the consumer's responsibility — rule 8 of the consumer rules linked from the README. */
227
209
  export const PharosFontFamilySans: string;
228
210
  /** Default monospace stack for code. */
229
211
  export const PharosFontFamilyMono: string;
@@ -308,16 +290,6 @@ export const PharosTypeH4FontWeight: string;
308
290
  export const PharosTypeH4LineHeight: string;
309
291
  /** H4 (xl). */
310
292
  export const PharosTypeH4LetterSpacing: string;
311
- /** DEPRECATED: use --pharos-type-h4. Removed in the next major. */
312
- export const PharosTypeLessonTitleFontFamily: string;
313
- /** DEPRECATED: use --pharos-type-h4. Removed in the next major. */
314
- export const PharosTypeLessonTitleFontSize: string;
315
- /** DEPRECATED: use --pharos-type-h4. Removed in the next major. */
316
- export const PharosTypeLessonTitleFontWeight: string;
317
- /** DEPRECATED: use --pharos-type-h4. Removed in the next major. */
318
- export const PharosTypeLessonTitleLineHeight: string;
319
- /** DEPRECATED: use --pharos-type-h4. Removed in the next major. */
320
- export const PharosTypeLessonTitleLetterSpacing: string;
321
293
  /** Subtitles (lg). */
322
294
  export const PharosTypeSubtitleFontFamily: string;
323
295
  /** Subtitles (lg). */
package/dist/tokens.js CHANGED
@@ -86,15 +86,6 @@ export const PharosZIndexModal = "1400"; // Modal UI: Dialog and Sheet panels.
86
86
  export const PharosZIndexPopover = "1500"; // Anchored floating UI: Popover, DropdownMenu, Select and Combobox lists. Above modal so it can open from inside a Dialog or Sheet.
87
87
  export const PharosZIndexToast = "1700"; // Toasts and transient notifications.
88
88
  export const PharosZIndexTooltip = "1800"; // Tooltips: always on top.
89
- export const PharosZ0 = "0"; // DEPRECATED: use --pharos-z-index-base (decision D29). Removed in the next major.
90
- export const PharosZHeader = "1000"; // DEPRECATED: use --pharos-z-index-sticky (decision D29). Removed in the next major.
91
- export const PharosZAboveHeader = "1100"; // DEPRECATED: use --pharos-z-index-sticky (decision D29). Removed in the next major.
92
- export const PharosZModalOverlay = "9998"; // DEPRECATED: use --pharos-z-index-overlay (decision D29). Removed in the next major.
93
- export const PharosZModal = "9999"; // DEPRECATED: use --pharos-z-index-modal (decision D29). Removed in the next major.
94
- export const PharosZDrawerOverlay = "9999"; // DEPRECATED: use --pharos-z-index-overlay (decision D29). Removed in the next major.
95
- export const PharosZDrawer = "10000"; // DEPRECATED: use --pharos-z-index-modal (decision D29). Removed in the next major.
96
- export const PharosZDropdown = "10001"; // DEPRECATED: use --pharos-z-index-popover (decision D29). Removed in the next major.
97
- export const PharosZTooltip = "10002"; // DEPRECATED: use --pharos-z-index-tooltip (decision D29). Removed in the next major.
98
89
  export const PharosDurationFast = "100ms"; // Micro interactions (hover).
99
90
  export const PharosDurationNormal = "200ms"; // Default transitions.
100
91
  export const PharosDurationSlow = "300ms"; // Panel slide, overlay fade.
@@ -119,7 +110,7 @@ export const PharosSpacing05 = "0.125rem"; // 2px step of the rem scale.
119
110
  export const PharosSpacing15 = "0.375rem"; // 6px step of the rem scale.
120
111
  export const PharosSpacing25 = "0.625rem"; // 10px step of the rem scale.
121
112
  export const PharosFontFamilySans =
122
- '"Outfit", Inter, system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif'; // Default sans-serif stack. Outfit is the primary face (Decision D8); Inter is the fallback before system fonts. Loading Outfit is the consumer's responsibility — see RULES.md §8.
113
+ '"Outfit", Inter, system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif'; // Default sans-serif stack. Outfit is the primary face (Decision D8); Inter is the fallback before system fonts. Loading Outfit is the consumer's responsibility — rule 8 of the consumer rules linked from the README.
123
114
  export const PharosFontFamilyMono =
124
115
  'ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace'; // Default monospace stack for code.
125
116
  export const PharosFontWeightRegular = "400";
@@ -173,12 +164,6 @@ export const PharosTypeH4FontSize = "1.25rem"; // H4 (xl).
173
164
  export const PharosTypeH4FontWeight = "600"; // H4 (xl).
174
165
  export const PharosTypeH4LineHeight = "1.25"; // H4 (xl).
175
166
  export const PharosTypeH4LetterSpacing = "0"; // H4 (xl).
176
- export const PharosTypeLessonTitleFontFamily =
177
- '"Outfit", Inter, system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif'; // DEPRECATED: use --pharos-type-h4. Removed in the next major.
178
- export const PharosTypeLessonTitleFontSize = "1.25rem"; // DEPRECATED: use --pharos-type-h4. Removed in the next major.
179
- export const PharosTypeLessonTitleFontWeight = "600"; // DEPRECATED: use --pharos-type-h4. Removed in the next major.
180
- export const PharosTypeLessonTitleLineHeight = "1.25"; // DEPRECATED: use --pharos-type-h4. Removed in the next major.
181
- export const PharosTypeLessonTitleLetterSpacing = "0"; // DEPRECATED: use --pharos-type-h4. Removed in the next major.
182
167
  export const PharosTypeSubtitleFontFamily =
183
168
  '"Outfit", Inter, system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif'; // Subtitles (lg).
184
169
  export const PharosTypeSubtitleFontSize = "1.125rem"; // Subtitles (lg).
package/dist/tokens.json CHANGED
@@ -115,17 +115,6 @@
115
115
  "toast": "1700",
116
116
  "tooltip": "1800"
117
117
  },
118
- "z": {
119
- "0": "0",
120
- "header": "1000",
121
- "above-header": "1100",
122
- "modal-overlay": "9998",
123
- "modal": "9999",
124
- "drawer-overlay": "9999",
125
- "drawer": "10000",
126
- "dropdown": "10001",
127
- "tooltip": "10002"
128
- },
129
118
  "duration": {
130
119
  "fast": "100ms",
131
120
  "normal": "200ms",
@@ -223,13 +212,6 @@
223
212
  "lineHeight": "1.25",
224
213
  "letterSpacing": "0"
225
214
  },
226
- "lesson-title": {
227
- "fontFamily": "\"Outfit\", Inter, system-ui, -apple-system, \"Segoe UI\", Roboto, \"Helvetica Neue\", Arial, sans-serif",
228
- "fontSize": "1.25rem",
229
- "fontWeight": "600",
230
- "lineHeight": "1.25",
231
- "letterSpacing": "0"
232
- },
233
215
  "subtitle": {
234
216
  "fontFamily": "\"Outfit\", Inter, system-ui, -apple-system, \"Segoe UI\", Roboto, \"Helvetica Neue\", Arial, sans-serif",
235
217
  "fontSize": "1.125rem",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@code-sherpas/pharos-tokens",
3
- "version": "0.8.0",
3
+ "version": "1.0.0",
4
4
  "description": "Design tokens de Code Sherpas — agnóstico de framework. DTCG + Style Dictionary + OKLCH.",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -18,8 +18,7 @@
18
18
  "type": "module",
19
19
  "files": [
20
20
  "dist",
21
- "src",
22
- "RULES.md"
21
+ "src"
23
22
  ],
24
23
  "exports": {
25
24
  ".": {
@@ -30,7 +29,8 @@
30
29
  "./dtcg/*": "./src/*.tokens.json"
31
30
  },
32
31
  "engines": {
33
- "node": ">=22"
32
+ "node": ">=22",
33
+ "pnpm": "10.33.0"
34
34
  },
35
35
  "lint-staged": {
36
36
  "*.{ts,tsx,js,mjs,cjs,json,md,mdx,css,yml,yaml}": "prettier --write"
@@ -53,8 +53,8 @@
53
53
  "vitest": "^4.1.4"
54
54
  },
55
55
  "scripts": {
56
- "build": "node build/style-dictionary.config.mjs",
57
- "test": "vitest run",
56
+ "build": "bash scripts/check-node-version.sh && node build/style-dictionary.config.mjs",
57
+ "test": "bash scripts/check-node-version.sh && vitest run",
58
58
  "test:watch": "vitest",
59
59
  "typecheck": "tsc --noEmit",
60
60
  "lint": "eslint .",
@@ -58,62 +58,6 @@
58
58
  "$description": "Tooltips: always on top."
59
59
  }
60
60
  },
61
- "z": {
62
- "0": {
63
- "$value": "0",
64
- "$type": "number",
65
- "$description": "DEPRECATED: use --pharos-z-index-base (decision D29). Removed in the next major.",
66
- "$deprecated": "Use {zIndex.base} (decision D29). Removed in the next major."
67
- },
68
- "header": {
69
- "$value": "1000",
70
- "$type": "number",
71
- "$deprecated": "Use {zIndex.sticky} (decision D29). Removed in the next major.",
72
- "$description": "DEPRECATED: use --pharos-z-index-sticky (decision D29). Removed in the next major."
73
- },
74
- "above-header": {
75
- "$value": "1100",
76
- "$type": "number",
77
- "$deprecated": "Use {zIndex.sticky} (decision D29). Removed in the next major.",
78
- "$description": "DEPRECATED: use --pharos-z-index-sticky (decision D29). Removed in the next major."
79
- },
80
- "modal-overlay": {
81
- "$value": "9998",
82
- "$type": "number",
83
- "$deprecated": "Use {zIndex.overlay} (decision D29). Removed in the next major.",
84
- "$description": "DEPRECATED: use --pharos-z-index-overlay (decision D29). Removed in the next major."
85
- },
86
- "modal": {
87
- "$value": "9999",
88
- "$type": "number",
89
- "$deprecated": "Use {zIndex.modal} (decision D29). Removed in the next major.",
90
- "$description": "DEPRECATED: use --pharos-z-index-modal (decision D29). Removed in the next major."
91
- },
92
- "drawer-overlay": {
93
- "$value": "9999",
94
- "$type": "number",
95
- "$deprecated": "Use {zIndex.overlay} (decision D29). Removed in the next major.",
96
- "$description": "DEPRECATED: use --pharos-z-index-overlay (decision D29). Removed in the next major."
97
- },
98
- "drawer": {
99
- "$value": "10000",
100
- "$type": "number",
101
- "$deprecated": "Use {zIndex.modal} (decision D29). Removed in the next major.",
102
- "$description": "DEPRECATED: use --pharos-z-index-modal (decision D29). Removed in the next major."
103
- },
104
- "dropdown": {
105
- "$value": "10001",
106
- "$type": "number",
107
- "$deprecated": "Use {zIndex.popover} (decision D29). Removed in the next major.",
108
- "$description": "DEPRECATED: use --pharos-z-index-popover (decision D29). Removed in the next major."
109
- },
110
- "tooltip": {
111
- "$value": "10002",
112
- "$type": "number",
113
- "$description": "DEPRECATED: use --pharos-z-index-tooltip (decision D29). Removed in the next major.",
114
- "$deprecated": "Use {zIndex.tooltip} (decision D29). Removed in the next major."
115
- }
116
- },
117
61
  "duration": {
118
62
  "fast": {
119
63
  "$value": "100ms",
@@ -4,7 +4,7 @@
4
4
  "sans": {
5
5
  "$value": "\"Outfit\", Inter, system-ui, -apple-system, \"Segoe UI\", Roboto, \"Helvetica Neue\", Arial, sans-serif",
6
6
  "$type": "fontFamily",
7
- "$description": "Default sans-serif stack. Outfit is the primary face (Decision D8); Inter is the fallback before system fonts. Loading Outfit is the consumer's responsibility — see RULES.md §8."
7
+ "$description": "Default sans-serif stack. Outfit is the primary face (Decision D8); Inter is the fallback before system fonts. Loading Outfit is the consumer's responsibility — rule 8 of the consumer rules linked from the README."
8
8
  },
9
9
  "mono": {
10
10
  "$value": "ui-monospace, SFMono-Regular, \"SF Mono\", Menlo, Consolas, \"Liberation Mono\", monospace",
@@ -171,18 +171,6 @@
171
171
  },
172
172
  "$description": "H4 (xl)."
173
173
  },
174
- "lesson-title": {
175
- "$type": "typography",
176
- "$value": {
177
- "fontFamily": "{font.family.sans}",
178
- "fontSize": "{font.size.xl}",
179
- "fontWeight": "{font.weight.semibold}",
180
- "lineHeight": "{font.lineHeight.tight}",
181
- "letterSpacing": "{font.letterSpacing.normal}"
182
- },
183
- "$description": "DEPRECATED: use --pharos-type-h4. Removed in the next major.",
184
- "$deprecated": "Use --pharos-type-h4: Pharos names text styles by their level, not by one product's content. Removed in the next major."
185
- },
186
174
  "subtitle": {
187
175
  "$type": "typography",
188
176
  "$value": {
package/RULES.md DELETED
@@ -1,60 +0,0 @@
1
- # Rules for consumers of `@code-sherpas/pharos-tokens`
2
-
3
- This file ships with the package (`files` includes `RULES.md`). Every
4
- consumer — `pharos-react`, `alexandria-web-application`,
5
- and any future app — must follow these rules.
6
-
7
- ## 1. Do not redefine values locally
8
-
9
- Tokens are the single source of truth. Forbidden:
10
-
11
- - Hardcoded hex for colors that have an equivalent token (e.g. `#101820` when `--pharos-color-neutral-900` exists).
12
- - Raw `rem`/`px` values for spacing when `--pharos-spacing-*` exists.
13
- - Ad-hoc local shadows.
14
-
15
- If a value has no token, open an issue in this repo. Do not improvise.
16
-
17
- ## 2. Do not invent colors outside the system
18
-
19
- The system is: `color.neutral.*`, `color.primary.*`, `color.semantic.{success,error,warning,info}.*`, `color.base.{white,black}`. If you need a new accent (purple, amber, etc.) with clear semantics, open an issue — do not add it locally.
20
-
21
- ## 3. Use CSS vars or the JS object
22
-
23
- **Web**: import `@code-sherpas/pharos-tokens/css` at your entry point and use `var(--pharos-*)` or Tailwind arbitrary values (`bg-[var(--pharos-color-primary-600)]`).
24
-
25
- **Programmatic** (JS/TS): `import { tokens } from '@code-sherpas/pharos-tokens'` → `tokens.color.neutral['900']`.
26
-
27
- **DTCG source** (for custom pipelines): `import dtcg from '@code-sherpas/pharos-tokens/dtcg/color'`.
28
-
29
- ## 4. Do not mutate values after importing
30
-
31
- Forbidden: `tokens.color.primary['600'] = '#new'`. The object is frozen in spirit even if JS does not enforce it. Changes go through a PR to this repo.
32
-
33
- ## 5. Respect semver
34
-
35
- - Breaking change in this repo → major bump → consumers upgrade explicitly.
36
- - New token → minor bump → consumers may adopt without breaking anything.
37
- - Value adjustment without renaming → patch → consumers receive visual improvements automatically.
38
-
39
- ## 6. Accessibility
40
-
41
- When picking which tokens to use, respect the defined pairs:
42
-
43
- - Text over `color.neutral.50`/`100`/`200`: use `color.neutral.900` or darker.
44
- - Text over `color.primary.600`+: use `color.base.white`.
45
- - Text over `color.semantic.{success,error,info}.fg` (filled): use `.on` from the same group.
46
- - Text over `color.semantic.warning.fg`: `.on` is `color.neutral.900` (warning is light).
47
-
48
- ## 7. Extensions and overrides
49
-
50
- **Do not** publish a new package `@yourorg/pharos-tokens-extended`. If a product needs its own tokens (e.g. co-branded identities), implement them as additional CSS vars in the consumer under your own namespace (`--myapp-*`) and document it.
51
-
52
- ## 8. Font loading is the consumer's responsibility
53
-
54
- `pharos-tokens` declares the font stack (e.g. `"Outfit", Inter, system-ui, ...`) but does **not** ship font files. The package stays framework-agnostic and cannot assume how the consumer serves assets. Each consumer is responsible for loading the primary face before the UI renders:
55
-
56
- - **Next.js**: `next/font/google` with `Outfit` (and optionally `Inter`) in the root layout.
57
- - **Vite / CRA / generic web**: `@fontsource/outfit` + `@fontsource/inter`, or a `<link>` tag to Google Fonts.
58
- - **Emails / PDFs**: the renderer falls back through the stack; declare `Outfit` as the primary face only if the renderer can embed it, otherwise the fallback chain kicks in.
59
-
60
- If the primary face is not loaded, the stack falls back through `Inter → system-ui → ...`, so the UI degrades gracefully — but the intended design requires the primary face.