@contentful/experience-design-system-cli 2.2.1

package/skills/generate-tokens.md

@@ -0,0 +1,194 @@
+# Generate Tokens — Classification Skill
+
+## Purpose
+
+Classify every raw token from the input into a DTCG token tree. Output one JSON tool call per line to stdout. The CLI reads your stdout and writes each token and group directly to the pipeline database — you do not produce a JSON file.
+
+---
+
+## Prerequisites — Input
+
+All input is embedded inline in the prompt before this file:
+
+- **Raw token source** — the original source file as-is. This may be any format: SCSS/CSS variable declarations, a JavaScript/TypeScript token module, a JSON object, a Style Dictionary config, Tailwind config, or any other token definition format the project uses. Read it as you would any source file.
+- **Token-name sidecar** — if provided, maps raw names to DTCG paths (read-only context). Use these as authoritative path assignments when present.
+
+---
+
+## Target schema
+
+The CLI assembles your output into a DTCG token tree. Each `set_group` call produces an intermediate group node; each `set_token` call produces a leaf with `$type` and `$value`. You do not produce JSON directly — emit tool calls and the CLI writes the rows.
+
+---
+
+## Output protocol
+
+Emit one JSON object per line. The CLI parses lines starting with `{`. Lines not starting with `{` are treated as prose and ignored — use them freely for reasoning.
+
+**Two tool calls:**
+
+```
+{"tool":"set_group","path":"<dot.notation.path>","description":"<optional>"}
+
+{"tool":"set_token","path":"<dot.notation.path>","type":"<DTCG type>","value":<value>,"description":"<reason>"}
+```
+
+Every leaf token must have an explicit `$type` — do not rely on group-level inheritance. Intermediate nodes (groups) must NOT have a `type` field.
+
+**Rules:**
+- Emit exactly one JSON object per line. No multi-line JSON.
+- Every intermediate group must have a `set_group` call.
+- Every leaf token must have a `set_token` call.
+- `path` is dot-notation from root, e.g. `colors.brand.primary` — no leading dots or slashes.
+- `type` must be one of the 13 valid DTCG types (see table below).
+- `value` must be valid JSON — string, number, array, or object depending on the type. Do NOT quote complex values.
+- Emit `set_group` calls before the `set_token` calls under them.
+- `description` on `set_token` documents your reasoning — always include it.
+
+---
+
+## Valid types
+
+Exactly **13** valid DTCG `$type` values:
+
+| type | Typical values |
+|---|---|
+| `color` | `"#0066ff"`, `"rgb(0,102,255)"` |
+| `dimension` | `"8px"`, `"1rem"`, `"0.5em"` |
+| `fontFamily` | `"Inter, sans-serif"` |
+| `fontWeight` | `400`, `"bold"` |
+| `duration` | `"200ms"`, `"0.3s"` |
+| `cubicBezier` | `[0.42, 0, 0.58, 1]` |
+| `number` | `1.5`, `100` |
+| `strokeStyle` | `"solid"`, `"dashed"` |
+| `border` | `{"width":"1px","style":"solid","color":"#000"}` |
+| `transition` | `{"duration":"200ms","timingFunction":[0.42,0,0.58,1],"delay":"0ms"}` |
+| `shadow` | `{"offsetX":"0px","offsetY":"4px","blur":"8px","spread":"0px","color":"#00000026"}` |
+| `gradient` | `[{"color":"#000","position":0},{"color":"#fff","position":1}]` |
+| `typography` | `{"fontFamily":"Inter","fontSize":"16px","fontWeight":400,"lineHeight":1.5,"letterSpacing":"0px"}` |
+
+---
+
+## Mapping guidance — Type resolution
+
+For each token value, determine the DTCG `$type` by reading the value and its context:
+
+| Value pattern | Type |
+|---|---|
+| Starts with `#`, `rgb(`, `hsl(`, `rgba(` | `color` |
+| Ends with `px`, `rem`, `em`, `%`, `vw`, `vh` | `dimension` |
+| `cubic-bezier(...)` or 4-element array | `cubicBezier` |
+| Ends with `ms` or `s` (animation/transition) | `duration` |
+| Font family name string | `fontFamily` |
+| Numeric `100`–`900`, or `bold`/`normal`/`light` | `fontWeight` |
+| Multi-property shadow value | `shadow` |
+| Multi-property border value | `border` |
+| `solid`, `dashed`, `dotted` alone | `strokeStyle` |
+| Composite font shorthand | `typography` |
+| Unitless number | `number` |
+
+When a token's type is ambiguous from its value alone, use its name as context (e.g. `$spacing-*` → `dimension`, `$duration-*` → `duration`). Document your reasoning in `description`. If no type fits, use `number` with a `"WARNING: type unknown"` description.
+
+Resolve variable references: if a value references another variable (e.g. SCSS `$black` in `rgba($black, 0.6)`, or a JS alias), substitute the referenced value before classifying.
+
+---
+
+## Grouping
+
+Organize tokens into a nested DTCG hierarchy that reflects their semantic purpose:
+
+1. Examine naming patterns and existing structure in the source (variable prefixes, object nesting, file-level categories).
+2. **For already-nested sources (JS/TS objects, JSON, Style Dictionary)**: derive paths directly from the source key hierarchy — lowercase each key segment and join with dots. Do NOT reorganize, rename, or flatten unless the original key is purely implementation-specific (e.g. `DEFAULT` as a single-child wrapper can be elided). The source structure IS the path. Example: `tokens[SPACING].DEFAULT.8` → `spacing.8`; `tokens[COLOR].text.standard` → `color.text.standard`; `tokens[SHADOW].level.1` → `shadow.level.1`.
+3. For flat names (SCSS variables, CSS custom properties): strip leading `--` or `$`; replace `-` and `_` separators with `.` to form nested paths. Use the first meaningful segment as the top-level group.
+4. If neither rule applies, propose a grouping strategy: by kind (`colors`, `spacing`, `typography`), by semantic role (`brand`, `semantic`, `neutral`), or hybrid.
+5. Emit a `set_group` call for every intermediate node before emitting any `set_token` calls under it.
+
+**Determinism rule**: Identical source input MUST produce identical paths on every run. Never invent synonyms, abbreviations, or alternative hierarchies for keys that already exist in the source. If `primary` is the key, the path segment is `primary` — not `brand-primary`, `main`, or `accent`.
+
+If the token-name sidecar is provided, use it as authoritative path assignments — it maps raw names to DTCG dot-notation paths already.
+
+---
+
+## Value handling
+
+Most values pass through as strings. For composite types, parse the raw string into the required JSON structure:
+
+**`border`** — parse `1px solid #ccc` into:
+```json
+{"width":"1px","style":"solid","color":"#cccccc"}
+```
+
+**`shadow`:**
+```json
+{"offsetX":"0px","offsetY":"4px","blur":"8px","spread":"0px","color":"#00000026"}
+```
+
+**`transition`:**
+```json
+{"duration":"200ms","delay":"0ms","timingFunction":[0.42,0,0.58,1]}
+```
+
+**`gradient`** — array of color stops:
+```json
+[{"color":"#000","position":0},{"color":"#fff","position":1}]
+```
+
+---
+
+## Examples
+
+Input (SCSS):
+```scss
+$brand-primary: #0066ff;
+$spacing-sm: 8px;
+$anim-speed: 200ms;
+$black: #1a1a1a;
+$overlay: rgba($black, 0.6);
+```
+
+Output:
+```
+Analyzing SCSS variables: 5 tokens across color, spacing, duration, and composite color categories.
+$overlay references $black — resolving to rgba(26, 26, 26, 0.6).
+{"tool":"set_group","path":"colors","description":"Brand and UI color tokens"}
+{"tool":"set_group","path":"colors.brand","description":"Brand palette"}
+{"tool":"set_token","path":"colors.brand.primary","type":"color","value":"#0066ff","description":"Brand primary color"}
+{"tool":"set_token","path":"colors.neutral.black","type":"color","value":"#1a1a1a","description":"Base black neutral"}
+{"tool":"set_token","path":"colors.neutral.overlay","type":"color","value":"rgba(26, 26, 26, 0.6)","description":"Semi-transparent overlay; $black variable resolved to #1a1a1a"}
+{"tool":"set_group","path":"spacing","description":"Spacing scale"}
+{"tool":"set_token","path":"spacing.sm","type":"dimension","value":"8px","description":"Small spacing step"}
+{"tool":"set_group","path":"motion","description":"Animation timing"}
+{"tool":"set_group","path":"motion.duration","description":"Duration values"}
+{"tool":"set_token","path":"motion.duration.speed","type":"duration","value":"200ms","description":"Standard animation speed"}
+```
+
+---
+
+## Edge cases
+
+- **Empty input** — emit nothing; the CLI will report 0 tokens stored.
+- **Path collision** — two raw tokens resolve to the same dot-notation path: append `_2`, `_3` to disambiguate, and add a `description` warning.
+- **Unrecognizable value** — no heuristic matches and `inferredKind` is invalid → use `number` with a warning in `description`.
+- **Complex composite value** — parse raw string into the required JSON structure; if parsing is ambiguous, use a best-effort parse and document in `description`.
+
+---
+
+## Validation step — Pre-emit checklist
+
+Before emitting any tool calls, verify:
+
+1. Every raw token in the input has exactly one `set_token` call.
+2. Every intermediate group has a `set_group` call.
+3. All `type` values are from the 13 valid DTCG types.
+4. `value` is valid JSON for the given type (string for color/dimension/etc., object for border/shadow/etc., array for gradient/cubicBezier).
+5. All `path` values use dot-notation with no leading dots or slashes.
+6. No duplicate paths.
+7. `set_group` calls precede the `set_token` calls under them.
+
+After the run, the developer can validate with:
+
+```
+experience-design-system-cli print validate --tokens <out-path>
+```
+
+Re-run or iterate on any tokens flagged by warnings until validation passes.

package/skills/select-components.md

@@ -0,0 +1,180 @@
+# Analyze Select — Agent Component Selection Skill
+
+## Purpose
+
+Review the single extracted React/Next.js component provided below and decide whether it belongs in **Contentful Experience Orchestration** as a Component Type. Output one JSON tool call to stdout.
+
+---
+
+## What is Contentful Experience Orchestration?
+
+Contentful Experience Orchestration is a Contentful product that enables **designers, developers, and marketers** to compose and manage digital experiences in Contentful. Component Types are used at every layer of the design system:
+
+- **Atoms** — low-level UI primitives: icons, buttons, inputs, badges
+- **Molecules** — composed UI units: cards, search fields, modals, navigation items
+- **Organisms** — larger sections: heroes, banners, footers, press release lists, parallax sections
+
+All three levels are valid Component Types in Contentful Experience Orchestration. Designers and developers compose atoms into molecules, molecules into organisms. Marketers then configure content and design values on any of these.
+
+The entity being defined — a **Component Type** — is the schema that tells Contentful what is configurable for this component. It defines design properties, content properties, and slots. Even a component with only a few configurable props is a valid Component Type.
+
+---
+
+## The one rule: does it render visible UI?
+
+**Accept** the component if it renders visible UI — regardless of whether it is an atom, molecule, or organism, and regardless of whether it has many or few configurable props. A footer icon with two props (`icon`, `label`) is just as valid as a parallax hero with fifteen props.
+
+**Reject** the component only if its primary purpose produces zero visual output:
+- It is a React hook (name starts `use` or `Use`)
+- It is a pure context provider with no visual output
+- It is a Ninetailed/personalization platform wrapper (its job is routing to variants, not rendering content)
+- It is an analytics/event-tracking component (fires events, renders nothing)
+- It is a security or infrastructure utility (no UI at all)
+
+---
+
+## What NOT to use as a rejection reason
+
+These are **not** valid reasons to reject a component:
+
+| Invalid reason | Why it is wrong |
+|---|---|
+| "Only atoms/low-level" | Atoms are first-class Component Types in Contentful Experience Orchestration |
+| "Tightly coupled to a parent component" | Contentful Experience Orchestration handles composition at the experience layer |
+| "Has A/B testing or personalization-related props" | These props are classified as `state` or excluded in the generate step — their presence does not disqualify the component |
+| "Has no marketer-configurable props" | Marketers are not the only users; designers and developers configure components too |
+| "Domain-specific or feature-level" | Press releases, newsrooms, search — all valid content components |
+| "Server-side or SSR" | Server components that render visible UI are valid |
+| "Few configurable props" | One or two props is fine |
+
+---
+
+## Reject only these categories
+
+| Category | Why |
+|---|---|
+| **React hooks** | `useXxx` / `UseXxx` — functions, not renderable components. Zero visual output. |
+| **Pure context providers** | Wrap children to pass context but render no UI themselves |
+| **A/B testing or personalization wrappers** | Components whose *entire purpose* is routing users to content variants or tracking experiment participation — they render no UI of their own |
+| **Analytics and event tracking** | Components that only fire analytics events and render nothing visible |
+| **Security utilities** | Non-visual security primitives with no rendered output |
+
+> **Variant routing rule**: Reject a component if its entire purpose is deciding *which* content variant to show — that is framework infrastructure, not a Component Type. Do **not** reject a component merely because it *contains* some A/B testing or personalization-related props — those props are handled as `state` in the generate step.
+
+---
+
+## Output protocol
+
+Emit one JSON object on a single line. Lines not starting with `{` are ignored by the parser — use them freely for reasoning.
+
+**Two tool calls — emit exactly one:**
+
+```
+{"tool":"select_component","name":"<ComponentName>","reason":"<brief reason>"}
+
+{"tool":"reject_component","name":"<ComponentName>","reason":"<brief reason>"}
+```
+
+**Rules:**
+- Emit exactly one JSON object, on one line. No multi-line JSON. No markdown fences.
+- The `name` must match the component name in the input.
+- `reason` is a brief phrase documenting your decision.
+- Emit prose lines (not starting with `{`) to log your reasoning before the final tool call.
+
+---
+
+## Examples
+
+```
+Analytics — fires analytics events, no visual output
+{"tool":"reject_component","name":"Analytics","reason":"analytics tracker — no visual output"}
+```
+
+```
+CanaryToken — security utility, no visual output
+{"tool":"reject_component","name":"CanaryToken","reason":"security utility — no visual output"}
+```
+
+```
+ClientExperience — personalization wrapper whose entire purpose is routing users to content variants
+{"tool":"reject_component","name":"ClientExperience","reason":"variant routing wrapper — entire purpose is A/B routing, not rendering UI"}
+```
+
+```
+ComponentMarker — experimentation marker component, no visual output
+{"tool":"reject_component","name":"ComponentMarker","reason":"experimentation marker — no visual output"}
+```
+
+```
+ComponentTracker — variant attribution tracker, no visual output
+{"tool":"reject_component","name":"ComponentTracker","reason":"variant attribution tracker — no visual output"}
+```
+
+```
+Refresh — client-side route refresh utility for personalization platform, no visual output
+{"tool":"reject_component","name":"Refresh","reason":"personalization route refresh utility — no visual output"}
+```
+
+```
+ServerExperience — server-side variant routing wrapper, no visual output
+{"tool":"reject_component","name":"ServerExperience","reason":"server-side variant routing wrapper — no visual output"}
+```
+
+```
+UseHelpNavigation — React hook, not a renderable component
+{"tool":"reject_component","name":"UseHelpNavigation","reason":"React hook — not a renderable component"}
+```
+
+```
+Providers — React context provider with no visual output
+{"tool":"reject_component","name":"Providers","reason":"pure context provider — no visual output"}
+```
+
+```
+FooterIcon — atom: renders an icon with optional label in the footer
+{"tool":"select_component","name":"FooterIcon","reason":"UI atom — renders icon with configurable icon and label"}
+```
+
+```
+FeedbackModal — modal dialog with visibility state
+{"tool":"select_component","name":"FeedbackModal","reason":"modal UI component with configurable visibility and content"}
+```
+
+```
+ActiveFilters — renders active filter chips with remove controls
+{"tool":"select_component","name":"ActiveFilters","reason":"filter UI component — renders visible filter chips"}
+```
+
+```
+FullSizeBarNoContent — full-width text bar with link; has some personalization state props
+The personalization props (hideContentForPersonalization, componentId) are state props handled in the generate step.
+The component renders real visual UI — a bar with text, chevron, and link.
+{"tool":"select_component","name":"FullSizeBarNoContent","reason":"content bar UI — renders visible bar with configurable text, link, and design"}
+```
+
+```
+ParallaxComponent — parallax marketing section; has some A/B testing props alongside real content props
+The A/B testing props (abmFallback, abmLinkedFromAccount) are state props, not the component's primary purpose.
+The component renders a parallax section with title, subtitle, and visual effects.
+{"tool":"select_component","name":"ParallaxComponent","reason":"marketing section UI — renders parallax content with configurable title, subtitle, and design"}
+```
+
+```
+NewsroomLandingPressReleases — press release list with pagination and locale
+{"tool":"select_component","name":"NewsroomLandingPressReleases","reason":"content list UI — renders press releases with configurable locale and pagination"}
+```
+
+```
+ServerHelpNavigation — server-side navigation with configurable search visibility and locale
+{"tool":"select_component","name":"ServerHelpNavigation","reason":"navigation UI — renders help navigation with configurable locale and search toggle"}
+```
+
+```
+TextImageCard — card with rich text and background image
+{"tool":"select_component","name":"TextImageCard","reason":"content card UI — configurable rich text, image, and layout"}
+```
+
+```
+SearchInput — search field with dropdown
+{"tool":"select_component","name":"SearchInput","reason":"search UI — configurable placeholder and state"}
+```