@vertekum/schema-atlassian 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thomas Schemmer
+
+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

@@ -0,0 +1,91 @@
+# @vertekum/schema-atlassian
+
+The [Atlassian Design System](https://atlassian.design/foundations/tokens/design-tokens) token
+path vocabulary, as JSON Schema files.
+
+## What a vocabulary governs
+
+**Names and order — nothing else.** These schemas enforce which names may appear, in what order,
+and where the order ends. What a granted name *is* — a group, a `$value` token, a `$ref` token, a
+group carrying a `$root` base value — is the token author's choice, validated by the DTCG format
+schema running in parallel, never by this one. Every position passes `$`-prefixed keys through
+unjudged for exactly that reason.
+
+`src/vocabulary.json` records the source's own base-value placements (the `.$root` entries); the
+schemas deliberately do not police them.
+
+## What is in the box
+
+Ten files, one variant each:
+
+| file | names |
+| --- | --- |
+| `color.json` | 430 |
+| `motion.json` | 62 |
+| `font.json` · `space.json` | 23 each |
+| `elevation.json` | 18 |
+| `radius.json` | 8 |
+| `border.json` | 3 |
+| `opacity.json` | 2 |
+| `utility.json` | 1 |
+| `atlassian.json` | all 570 |
+
+**Aspects seal their branch and leave the root open**, so several can validate the same files
+together without refusing each other's branches — the cost is that no aspect refuses an unknown
+*top-level* branch. `atlassian.json` is the wholesale schema that seals the root, for adopting the
+system entire.
+
+Every file is self-contained: no `$refs`, nothing to resolve.
+
+```
+$ my-validator tokens.json --schema color.json
+/color/text  'bland' is not permitted
+```
+
+## Extending
+
+Take a copy and edit it — the files are plain JSON Schema, and a copy is ordinary source:
+
+- to **grant a name**, add a position where it belongs:
+
+```json
+"marketing": {
+  "type": "object",
+  "properties": {},
+  "patternProperties": { "^\\$": true },
+  "unevaluatedProperties": false
+}
+```
+
+(That is the one position shape used everywhere: granted names in `properties`, `$`-keys passed
+through, everything else refused. Zero granted names means the path ends there.)
+
+- to **remove a name**, delete its position.
+
+An upstream update no longer flows into an edited copy — that is the trade of owning it: re-copy
+and re-apply the edit.
+
+## Derivation
+
+The vocabulary is derived, not hand-written. `src/vocabulary.json` holds the sorted name list —
+the reviewed artifact; the ten schemas are mechanical projections of it.
+
+570 of Atlassian's 585 names ship. Omitted, with reasons recorded in `scripts/derive.ts`:
+
+- `color.rovo.*`, `elevation.rovo.*` — Rovo is Atlassian's AI product surface, not a general vocabulary
+- `utility.UNSAFE.*` — a declared escape hatch, and a vocabulary should not bless one
+
+Also deliberately absent: `$type` per branch — a judgement the source artifact does not state.
+
+## Upgrading
+
+From this package's directory:
+
+```bash
+npm run derive              # re-derive from @atlaskit/tokens (a devDependency)
+git diff src/vocabulary.json  # the review artifact: added and removed names
+npm test                    # the schemas must still enforce what they claim
+```
+
+Read the diff before committing: removing a name starts refusing tokens a consuming project may
+still define.