UNPKG

@payfit/unity-themes

Version:

112 lines (85 loc) • 4.85 kB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
--- name: unity-themes description: > Use when selecting a Unity design token, resolving a token reference or CSS variable, writing responsive or state-based uy: utilities, merging classes, or defining typed style variants. Search the canonical token catalog first and use Unity's uyMerge, uyTv, and cn helpers instead of raw alternatives. metadata: type: core library: '@payfit/unity-themes' sources: - 'PayFit/hr-apps:libs/shared/unity/themes/src/agent-references/tokens-catalog.json' - 'PayFit/hr-apps:libs/shared/unity/themes/src/utils/tailwind-merge.ts' - 'PayFit/hr-apps:libs/shared/unity/themes/src/utils/tailwind-variants.ts' - 'PayFit/hr-apps:libs/shared/unity/themes/src/utils/cn.ts' - 'PayFit/hr-apps:libs/shared/unity/themes/src/scripts/build.ts' --- ## Source order Before implementation, perform a targeted search of `tokens-catalog.json` using `rg`, `jq`, or another file-reading command. Loading this skill alone does not count as consulting the catalog. 1. Read [src/agent-references/tokens-catalog.json](../../src/agent-references/tokens-catalog.json) for exact catalog names, CSS variables, token families, resolved default values, and references. 2. If the match is ambiguous or the raw definition is needed, inspect the DTCG files under `tokens/`. 3. For utility-class syntax and common blueprints, inspect the generated projections under `src/storybook-mcp/` (for example `semantic-surface-colors.mdx`). These files are optimized guides, not the canonical token index. Targeted lookup example: ```sh jq '.tokens[] | select(.name | test("border-neutral"; "i"))' \ libs/shared/unity/themes/src/agent-references/tokens-catalog.json ``` ## Standard operating procedure 1. Classify the request as a token name, CSS variable, generated class, resolved value, or design-intent question. 2. Search the entire catalog and compare exact semantic matches before considering primitives. 3. Use the catalog's `name` and `cssVariable`; do not reconstruct names from the DTCG path when a transform may have changed them. 4. Preserve token references. Inspect `values.default` to understand the current theme resolution, and inspect `references` when explaining an alias. 5. For classes, use the generated `src/storybook-mcp` blueprint for the relevant family and substitute only a catalog-confirmed token name. Do not enumerate or invent the complete class space. 6. Prefer semantic tokens for product UI. Use primitives only when the intent has no semantic equivalent or the user explicitly asks for a raw palette value. 7. Keep the `uy:` prefix on every Unity utility class. 8. Use `uyMerge` when external classes may collide with internal ones, `uyTv` for typed component variants, and `cn` for ad-hoc conditional strings. ```tsx <div className="uy:bg-surface-primary uy:text-content-primary" /> ``` Never assume that a plausible Tailwind name exists. If it is not represented by the catalog or an applicable blueprint, keep searching or state that no confirmed class was found. Prefer semantic tokens over primitive values and use the `uy:` prefix for Tailwind utilities. Do not invent utility names or expand the full class space; consult the catalog and use the semantic family that matches the element's role. ## Utility conventions - Prefix every class and modifier with `uy:`, for example `uy:md:gap-200` and `uy:data-[hovered=true]:bg-surface-primary-hover`. - Prefer a component's exposed `data-*` state over a raw pseudo-class when the component manages that state. - Import `uyMerge`, `uyTv`, `VariantProps`, and `cn` from `@payfit/unity-themes`; raw `tailwind-merge` and `tailwind-variants` are not configured for Unity tokens. - Use `uyTv` for a reusable component API with variant axes. Use `cn` for a small conditional class expression. Read [references/patterns.md](references/patterns.md) for focused examples of responsive and state modifiers, class merging, conditional classes, and typed variants. ## Common mistakes ### Omit the uy: prefix Bare Tailwind classes are absent from Unity's prefixed stylesheet and silently produce no styling. ```tsx // Wrong <div className="flex gap-4" /> // Correct <div className="uy:flex uy:gap-200" /> ``` ### Guess a plausible token name ```tsx // Wrong: standard Tailwind-looking names are not Unity tokens. <div className="uy:bg-primary-500 uy:text-gray-900" /> // Correct: both names are confirmed by tokens-catalog.json. <div className="uy:bg-surface-primary uy:text-content-primary" /> ``` ### Import unconfigured helpers ```tsx // Wrong import { twMerge } from 'tailwind-merge' import { tv } from 'tailwind-variants' // Correct import { uyMerge, uyTv } from '@payfit/unity-themes' ``` ## See also - `unity-layout` — choose and compose `Flex`, `Grid`, and semantic `Text` primitives from `@payfit/unity-components`.