@vertekum/schema-atlassian 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# @vertekum/schema-atlassian
+
+## 0.1.2
+
+### Patch Changes
+
+- [`9c0f093`](https://github.com/moros-oxus/vertekum/commit/9c0f093b5016c6c0ca9cb5b5fd48598718e698d9) Thanks [@tschemmer](https://github.com/tschemmer)! - The space vocabulary is declared with zero-padded scale ranges (`025-100/25 | 150-300/50 | 400-600/100`) instead of a hand-list; granted names are unchanged.
+
+## 0.1.1
+
+### Patch Changes
+
+- [`c8d9ce6`](https://github.com/moros-oxus/vertekum/commit/c8d9ce6040283afacd343e1d924cf31cff696eda) Thanks [@tschemmer](https://github.com/tschemmer)! - The vocabulary schemas are now built from grammar definition modules shipped beside them (`dfn/` in, `lib/` out); artifacts carry provenance stamps, and every import path is unchanged and flat (`@vertekum/schema-atlassian/color.json`, `…/color.dfn`).

package/README.md

@@ -18,24 +18,33 @@ schemas deliberately do not police them.
 
 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 |
+| file | shipped names | grants |
+| --- | --- | --- |
+| `color.json` | 430 | the documented grammar (generative) |
+| `motion.json` | 62 | paradigms + component shapes (generative) |
+| `elevation.json` | 18 | layer × kind × state (generative) |
+| `font.json` · `space.json` | 23 each | exactly what ships |
+| `radius.json` | 8 | exactly what ships |
+| `border.json` | 3 | exactly what ships |
+| `opacity.json` | 2 | exactly what ships |
+| `utility.json` | 1 | exactly what ships |
+| `atlassian.json` | all 570 | the union of the nine |
+
+**Generative aspects grant the system's grammar, not just its current catalogue.** Color follows
+the documented anatomy — `color.<property>.<role>.<emphasis>.<state>` — so a combination the
+rules permit (say, a background role at an emphasis Atlassian has not yet minted) validates,
+while a name outside the grammar still refuses. The grantable-but-unshipped surplus is pinned by
+test to an exact per-aspect count, so it only ever changes as a reviewed edit.
 
 **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.
+Every file is self-contained: any `$ref` is internal (`#/$defs/…`), nothing external to
+resolve. The schemas live in `lib/`, their definition sources in `dfn/` — but specifiers stay
+flat: `@vertekum/schema-atlassian/color.json` and `@vertekum/schema-atlassian/color.dfn` both
+resolve through the package's exports map, no folder in the path.
 
 ```
 $ my-validator tokens.json --schema color.json
@@ -67,8 +76,36 @@ 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.
+The vocabulary is derived, then curated. Three layers:
+
+- `src/vocabulary.json` — the sorted name list transcribed from `@atlaskit/tokens`: the review
+  artifact for upstream changes.
+- `dfn/*.dfn` — the **source**: each aspect declared as a grammar module
+  (built with `@vertekum/schema-builder`, a devDependency). One expression states names and
+  order; shared name-sets are named denotations:
+
+  ```dfn
+  property = background | text | icon | border
+  color-role = brand | danger | discovery | information | neutral | success | warning
+  emphasis = subtlest | subtler | subtle | bold | bolder | boldest
+  interaction = hovered | pressed
+
+  root = color.[
+      <property>.<role>?.<emphasis>?.<interaction>?
+    | <code>
+    | …
+    ]
+  ```
+
+  The root reads as the syntagm; `?` collapses an unused slot (`neutral.hovered` skips
+  emphasis); forks are their own named productions. Set modifiers derive narrowed sets in
+  place: `<emphasis [bold, bolder, boldest]>` picks members, `<direction ![left]>` omits one.
+
+  A definition module is importable too: `use "@vertekum/schema-atlassian/color.dfn"` exposes
+  its denotations, and `<@interaction>` pulls just the one you reference.
+- `lib/*.json` — the built schemas (`npm run build`). Each carries a `$comment` stamp naming its
+  module; the artifacts are regenerated, never hand-edited, and the test suite fails when they
+  are stale.
 
 570 of Atlassian's 585 names ship. Omitted, with reasons recorded in `scripts/derive.ts`:
 
@@ -82,9 +119,11 @@ Also deliberately absent: `$type` per branch — a judgement the source artifact
 From this package's directory:
 
 ```bash
-npm run derive              # re-derive from @atlaskit/tokens (a devDependency)
+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
+# apply the additions/removals to the dfn/ modules — a reviewed grammar edit
+npm run build                 # regenerate lib/ from dfn/
+npm test                      # parity: built schemas grant exactly the vocabulary
 ```
 
 Read the diff before committing: removing a name starts refusing tokens a consuming project may

package/dfn/atlassian.dfn

@@ -0,0 +1,15 @@
+id "vertekum://schema-atlassian/atlassian.json"
+title "Atlassian Design System — all branches"
+description "Token path vocabulary: which names may appear, in what order, and where the order ends. What a granted name IS — group, token, base value — belongs to the token author and the DTCG format schema."
+
+use "./border.dfn"
+use "./color.dfn"
+use "./elevation.dfn"
+use "./font.dfn"
+use "./motion.dfn"
+use "./opacity.dfn"
+use "./radius.dfn"
+use "./space.dfn"
+use "./utility.dfn"
+
+root = [<@border> | <@color> | <@elevation> | <@font> | <@motion> | <@opacity> | <@radius> | <@space> | <@utility>]

package/dfn/border.dfn

@@ -0,0 +1,6 @@
+id "vertekum://schema-atlassian/border.json"
+title "Atlassian Design System — border"
+description "Token path vocabulary: which names may appear, in what order, and where the order ends. What a granted name IS — group, token, base value — belongs to the token author and the DTCG format schema."
+scope "branch"
+
+root = border.width.[focused | selected]

package/dfn/color.dfn

@@ -0,0 +1,42 @@
+id "vertekum://schema-atlassian/color.json"
+title "Atlassian Design System — color"
+description "Token path vocabulary: which names may appear, in what order, and where the order ends. What a granted name IS — group, token, base value — belongs to the token author and the DTCG format schema."
+scope "branch"
+
+# The documented syntagm (atlassian.design/foundations/color): color.<property>.<role>.<emphasis>.<state>.
+# The root reads as that syntagm; a slot collapses when unused (`?`). Co-meronyms that fork from it
+# (code sub-vocabularies, chart, link, …) are their own named productions, kept as simple as possible.
+# The schema grants the GRAMMAR — combinations the system's rules permit — not merely today's catalogue.
+
+property = background | text | icon | border
+color-role = brand | danger | discovery | information | neutral | success | warning
+special-role = disabled | input | inverse | selected
+accent-color = blue | gray | green | lime | magenta | orange | purple | red | teal | yellow
+emphasis = subtlest | subtler | subtle | bold | bolder | boldest
+interaction = hovered | pressed
+
+role = [<color-role> | <special-role> | accent.<accent-color>]
+
+root = color.[
+    <property>.<role>?.<emphasis>?.<interaction>?
+  | <code>
+  | <chart>
+  | <inverse-on>
+  | border.[bold | code | focused]
+  | blanket.[danger | selected]
+  | interaction.<interaction>
+  | link.visited?.pressed?
+  | skeleton.subtle?
+  ]
+
+# Atlassian's own enumerative sub-vocabularies for code blocks.
+code = [
+    background.code.[[added | removed].[highlight | line] | default | gutter | highlight]
+  | text.code.[accent.[1 | 2] | comments | default | functions | gutter | keywords | numbers | operators | strings | tags]
+  ]
+
+chart-emphasis = <emphasis [bold, bolder, boldest]>
+chart = chart.[[<accent-color> | <color-role>].<chart-emphasis>?.hovered? | categorical.1-8/1.hovered?]
+
+# warning content on inverse (bold) surfaces — the one role that takes an inverse marker.
+inverse-on = [text | icon].warning.inverse

package/dfn/elevation.dfn

@@ -0,0 +1,14 @@
+id "vertekum://schema-atlassian/elevation.json"
+title "Atlassian Design System — elevation"
+description "Token path vocabulary: which names may appear, in what order, and where the order ends. What a granted name IS — group, token, base value — belongs to the token author and the DTCG format schema."
+scope "branch"
+
+# Syntagm: elevation.<layer>.<kind>.<state> — surfaces take interaction states; shadows do not.
+
+interaction = hovered | pressed
+surface-kind = container | overlay | raised | sunken
+
+root = elevation.[<surface> | <shadow>]
+
+surface = surface.<surface-kind>?.<interaction>?
+shadow = shadow.[overlay | raised | overflow.[perimeter | spread]?]

package/dfn/font.dfn

@@ -0,0 +1,13 @@
+id "vertekum://schema-atlassian/font.json"
+title "Atlassian Design System — font"
+description "Token path vocabulary: which names may appear, in what order, and where the order ends. What a granted name IS — group, token, base value — belongs to the token author and the DTCG format schema."
+scope "branch"
+
+root = font.[
+    body.[large | small]
+  | code
+  | family.[[body | code | heading] | brand.[body | heading]]
+  | heading.[large | medium | small | xlarge | xsmall | xxlarge | xxsmall]
+  | metric.[large | medium | small]
+  | weight.[bold | medium | regular | semibold]
+  ]

package/dfn/motion.dfn

@@ -0,0 +1,32 @@
+id "vertekum://schema-atlassian/motion.json"
+title "Atlassian Design System — motion"
+description "Token path vocabulary: which names may appear, in what order, and where the order ends. What a granted name IS — group, token, base value — belongs to the token author and the DTCG format schema."
+scope "branch"
+
+# Paradigms: components animate through <transition> (enter/exit); directional components add a
+# <direction>; keyframes run <io> (in/out). Durations and easings are the system's own scales.
+
+transition = enter | exit
+direction = bottom | left | right | top
+io = in | out
+interaction = hovered | pressed
+component = avatar | blanket | flag | label | modal | panel | spotlight
+duration = instant | xxshort | xshort | short | medium | long | xlong | xxlong
+
+root = motion.[
+    <component>.<transition>
+  | avatar.hovered
+  | flag.reposition
+  | button.<interaction>
+  | listitem.[<interaction> | selected]
+  | popup.<transition>.<direction>
+  | sidenav.<transition>.<direction [left, right]>
+  | duration.<duration>
+  | <easing>
+  | <keyframe>
+  ]
+
+easing = easing.[[in | out].[bold | practical] | inout.bold | spring]
+
+keyframe = keyframe.[fade.<io> | scale.<io>.[medium | small] | slide.<io>.<slide-direction>]
+slide-direction = [<direction ![left]>.short | left.[half | short]]

package/dfn/opacity.dfn

@@ -0,0 +1,6 @@
+id "vertekum://schema-atlassian/opacity.json"
+title "Atlassian Design System — opacity"
+description "Token path vocabulary: which names may appear, in what order, and where the order ends. What a granted name IS — group, token, base value — belongs to the token author and the DTCG format schema."
+scope "branch"
+
+root = opacity.[disabled | loading]

package/dfn/radius.dfn

@@ -0,0 +1,6 @@
+id "vertekum://schema-atlassian/radius.json"
+title "Atlassian Design System — radius"
+description "Token path vocabulary: which names may appear, in what order, and where the order ends. What a granted name IS — group, token, base value — belongs to the token author and the DTCG format schema."
+scope "branch"
+
+root = radius.[full | large | medium | small | tile | xlarge | xsmall | xxlarge]

package/dfn/space.dfn

@@ -0,0 +1,9 @@
+id "vertekum://schema-atlassian/space.json"
+title "Atlassian Design System — space"
+description "Token path vocabulary: which names may appear, in what order, and where the order ends. What a granted name IS — group, token, base value — belongs to the token author and the DTCG format schema."
+scope "branch"
+
+# The spacing scale, as scale expressions: a leading zero pads the emitted names.
+scale = 0 | 025-100/25 | 150-300/50 | 400-600/100 | 800 | 1000
+
+root = space.[<scale> | negative.<scale ![0, 500, 600, 800, 1000]>]

package/dfn/utility.dfn

@@ -0,0 +1,6 @@
+id "vertekum://schema-atlassian/utility.json"
+title "Atlassian Design System — utility"
+description "Token path vocabulary: which names may appear, in what order, and where the order ends. What a granted name IS — group, token, base value — belongs to the token author and the DTCG format schema."
+scope "branch"
+
+root = utility.elevation.surface.current