@canonical/token-types 0.2.0 → 0.3.1
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 +67 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
# @canonical/token-types
|
|
2
|
+
|
|
3
|
+
Shared TypeScript types for Canonical design token tooling. This package defines the JSON contract between the Terrazzo CSS plugin (producer) and the LSP (consumer) — the `tokens.json` artifact format.
|
|
4
|
+
|
|
5
|
+
## Installation
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
bun add -d @canonical/token-types
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## Usage
|
|
12
|
+
|
|
13
|
+
Import types for working with the `tokens.json` artifact:
|
|
14
|
+
|
|
15
|
+
```ts
|
|
16
|
+
import type { Artifact, ArtifactToken, ArtifactEnvelope } from "@canonical/token-types";
|
|
17
|
+
|
|
18
|
+
function loadTokens(json: ArtifactEnvelope): Artifact {
|
|
19
|
+
if ("tokens" in json) return json.tokens; // wrapped envelope
|
|
20
|
+
return json; // flat artifact
|
|
21
|
+
}
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
Use the runtime guard to narrow DTCG type strings:
|
|
25
|
+
|
|
26
|
+
```ts
|
|
27
|
+
import { isKnownDtcgTokenType } from "@canonical/token-types";
|
|
28
|
+
|
|
29
|
+
if (isKnownDtcgTokenType(token.type)) {
|
|
30
|
+
// token.type is narrowed to KnownDtcgTokenType
|
|
31
|
+
}
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
## Exports
|
|
35
|
+
|
|
36
|
+
### Types
|
|
37
|
+
|
|
38
|
+
| Type | Description |
|
|
39
|
+
|------|-------------|
|
|
40
|
+
| `Artifact` | The complete artifact: CSS variable name to token metadata. |
|
|
41
|
+
| `ArtifactToken` | A single token entry combining metadata, resolved values, source location, derivation, and registration fields. |
|
|
42
|
+
| `ArtifactTokenInit` | Input contract for constructing a DTCG-sourced artifact token. |
|
|
43
|
+
| `DerivedArtifactTokenInit` | Input contract for constructing a derived or plugin-generated token. |
|
|
44
|
+
| `ArtifactEnvelope` | Union of flat `Artifact` and `WrappedArtifactEnvelope` — the plugin may emit either. |
|
|
45
|
+
| `WrappedArtifactEnvelope` | Artifact payload with `version`, `generator`, and `tokens` fields. |
|
|
46
|
+
| `ArtifactDeclaration` | A declaration site (selector, file, line, enclosing at-rules). |
|
|
47
|
+
| `ArtifactAtRule` | An at-rule context (name + prelude). |
|
|
48
|
+
| `DtcgTokenType` | DTCG `$type` values — known literals with a string escape hatch for forward compatibility. |
|
|
49
|
+
| `KnownDtcgTokenType` | The known DTCG type literals (`color`, `dimension`, `number`, etc.). |
|
|
50
|
+
| `TokenTier` | Tier classification: `"primitive"`, `"semantic"`, or `"derived"`. |
|
|
51
|
+
| `ArtifactTier` | Tier strings carried by artifacts — known tiers plus a string escape hatch. |
|
|
52
|
+
| `DerivationKind` | Derivation formula kinds (`"hover"`, `"active"`, `"disabled"`, `"delta"`, etc.). |
|
|
53
|
+
|
|
54
|
+
### Runtime
|
|
55
|
+
|
|
56
|
+
| Export | Description |
|
|
57
|
+
|--------|-------------|
|
|
58
|
+
| `KNOWN_DTCG_TOKEN_TYPES` | `const` array of all recognised DTCG type literals. |
|
|
59
|
+
| `isKnownDtcgTokenType(value)` | Type guard narrowing a string to `KnownDtcgTokenType`. |
|
|
60
|
+
|
|
61
|
+
## Development
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
bun run build # Compile (tsc)
|
|
65
|
+
bun run test # Run type-level tests
|
|
66
|
+
bun run check # Type check
|
|
67
|
+
```
|