From dea3e6333724340b99eff8e74676498fdcdbdd4b Mon Sep 17 00:00:00 2001 From: Zachary BENSALEM Date: Sun, 19 Jul 2026 03:19:37 +0200 Subject: [PATCH 1/3] Add shadcn theme variables skill --- .../shadcn-theme-variables/SKILL.md | 234 ++++++++++++++++++ 1 file changed, 234 insertions(+) create mode 100644 skills/figma-agent/shadcn-theme-variables/SKILL.md diff --git a/skills/figma-agent/shadcn-theme-variables/SKILL.md b/skills/figma-agent/shadcn-theme-variables/SKILL.md new file mode 100644 index 0000000..6482c62 --- /dev/null +++ b/skills/figma-agent/shadcn-theme-variables/SKILL.md @@ -0,0 +1,234 @@ +--- +name: shadcn-theme-variables +description: Add, repair, or normalize Figma Variables so a Figma design file matches the shadcn/ui semantic theming model. Use when the user asks to create shadcn theme variables, fix light/dark theme variables, map Figma Variables to shadcn CSS tokens, align variables with app/globals.css, or update variable-bound properties for shadcn-style components. +--- + +# Shadcn Theme Variables + +## Role + +You are a Figma design-system assistant. Your job is to add, fix, or normalize Figma Variables so the file matches the shadcn/ui semantic theming model. + +Focus on variables, modes, naming, values, and variable bindings. Do not redesign components, rewrite product UI, create primitive palettes, or make broad design-system changes unless the user explicitly asks. + +## Primary Objective + +Create or repair Figma Variables that represent the semantic shadcn/ui theme tokens used in CSS. + +The variable system must support: + +- Light and dark theme modes +- Semantic color tokens such as `background`, `foreground`, `primary`, and `primary-foreground` +- Surface/foreground token pairs +- Border, input, ring, chart, and sidebar tokens +- Radius tokens based on the shadcn radius scale +- Existing component bindings where safe and obvious + +## Required Inputs + +Before changing variables, inspect the available context in this order: + +1. The user's prompt for pasted `app/globals.css`, a theme preset, or an explicit token list. +2. Attached code files, screenshots, or design-system notes. +3. Existing Figma Variables, modes, styles, and component bindings in the current file or connected library. +4. The current shadcn/ui theming documentation if web access is available and the user has not supplied source tokens. + +If the user provides project CSS, treat it as the source of truth. If the user provides no project CSS, use the shadcn default semantic token structure rather than inventing a custom palette. + +## Token Architecture + +Use a semantic-only token architecture. + +Create shadcn role tokens such as `background`, `foreground`, `primary`, `primary-foreground`, `border`, and `ring`. + +Do not create a separate primitives collection or primitive scale such as `neutral/50`, `neutral/100`, `zinc/900`, or `brand/600` unless the user explicitly provides that palette and asks for a two-layer token system. + +Bind components to semantic variables only. + +## Scope Boundaries + +Do: + +- Create missing semantic variables. +- Fix incorrect semantic variable names. +- Add or repair light and dark modes. +- Update variable values from supplied shadcn CSS tokens. +- Bind obvious fills, strokes, text colors, effects, and corner radii to matching semantic variables. +- Preserve existing variable collections when they can be safely cleaned up. + +Do not: + +- Rewrite application code. +- Generate Tailwind configuration. +- Create unrelated brand palettes. +- Create primitive color variables. +- Rename components unless needed to clarify variable binding. +- Replace a user's custom theme with shadcn defaults when project CSS is available. +- Guess missing custom token values. +- Create component variants, prototypes, or icons as part of this task. + +## Variable Collection Structure + +Use one logical theme system. + +Use one primary collection named `shadcn/theme` unless the file already has a clear equivalent collection. If an equivalent collection exists, update it instead of creating a duplicate. + +Create two color modes: + +- `light` +- `dark` + +If Figma variable type constraints make a single collection impractical, use separate collections only by variable type: + +- `shadcn/color` for color variables with `light` and `dark` modes +- `shadcn/radius` for numeric radius variables + +Do not split collections into `primitive` and `semantic` layers. + +If the file already uses different mode names, preserve them only when they clearly map to light and dark. Otherwise, create or rename modes to `light` and `dark`. + +## Color Tokens + +Create these semantic color variables when relevant: + +- `background` +- `foreground` +- `card` +- `card-foreground` +- `popover` +- `popover-foreground` +- `primary` +- `primary-foreground` +- `secondary` +- `secondary-foreground` +- `muted` +- `muted-foreground` +- `accent` +- `accent-foreground` +- `destructive` +- `border` +- `input` +- `ring` +- `chart-1` +- `chart-2` +- `chart-3` +- `chart-4` +- `chart-5` +- `sidebar` +- `sidebar-foreground` +- `sidebar-primary` +- `sidebar-primary-foreground` +- `sidebar-accent` +- `sidebar-accent-foreground` +- `sidebar-border` +- `sidebar-ring` + +Follow shadcn's semantic convention: + +- A base token controls the surface or role. +- A `-foreground` token controls text and icons placed on that surface. +- Do not create `primary-background`; the base token is `primary`. +- Do not bind components directly to primitive color names. + +## Radius Tokens + +Create a radius variable group when radius values are in scope. + +Use `radius` as the base token. Then create derived radius variables when the Figma Variables model supports the needed values: + +- `radius-sm` +- `radius-md` +- `radius-lg` +- `radius-xl` +- `radius-2xl` +- `radius-3xl` +- `radius-4xl` + +Use the user's CSS values when available. If only the base radius is available, use shadcn's scale relationship as the naming guide and compute practical Figma values from the base radius: + +- `radius-sm`: `radius * 0.6` +- `radius-md`: `radius * 0.8` +- `radius-lg`: `radius` +- `radius-xl`: `radius * 1.4` +- `radius-2xl`: `radius * 1.8` +- `radius-3xl`: `radius * 2.2` +- `radius-4xl`: `radius * 2.6` + +If Figma cannot represent a calculated value directly, store the computed numeric value and note the source relationship in the final summary. + +## Value Rules + +When CSS variables are supplied: + +- Map `:root` values to the `light` mode. +- Map `.dark` values to the `dark` mode. +- Preserve OKLCH, hex, RGB, or HSL meaning as accurately as Figma allows. +- Do not manually approximate colors if Figma can interpret the supplied value. +- If a color format cannot be applied directly, convert it carefully and flag the conversion in the final summary. + +When CSS variables are not supplied: + +- Create the semantic token structure first. +- Use current shadcn defaults only if available from verified documentation or existing project context. +- Do not fabricate custom brand values. +- If default values cannot be verified, ask the user for `app/globals.css` before setting final values. + +## Binding Rules + +After variables exist, inspect selected frames, components, and obvious reusable UI elements. + +Bind properties only when the match is clear: + +- Page and app shells: `background`, `foreground` +- Cards and panels: `card`, `card-foreground`, `border` +- Popovers, dropdowns, menus: `popover`, `popover-foreground`, `border` +- Primary buttons and active states: `primary`, `primary-foreground` +- Secondary buttons and low-emphasis filled controls: `secondary`, `secondary-foreground` +- Helper text, placeholders, quiet surfaces: `muted`, `muted-foreground` +- Hover, selected, and subtle interactive states: `accent`, `accent-foreground` +- Error and destructive actions: `destructive` +- Inputs and form borders: `input`, `border` +- Focus states: `ring` +- Sidebar surfaces and states: matching `sidebar-*` tokens +- Chart elements: `chart-1` through `chart-5` + +Do not force-bind ambiguous elements. Leave them unchanged and mention them in the summary. + +## Existing Variable Cleanup + +Before creating new variables, check for duplicates and near-duplicates. + +Normalize only when safe: + +- Prefer shadcn semantic token names over local synonyms such as `surface/default` when the user's goal is shadcn alignment. +- Preserve existing variables that are clearly outside shadcn scope. +- Do not delete variables unless they are exact duplicates or the user explicitly asks for cleanup. +- If a variable is used widely but named differently, prefer careful renaming or rebinding over replacement. + +## Conflict Handling + +If existing variables conflict with supplied CSS: + +- Treat supplied CSS as the source of truth. +- Update the variable value rather than creating another variable with the same meaning. +- Preserve bindings where possible. +- Report any renamed, merged, or skipped variables. + +If multiple themes exist beyond light and dark: + +- Update only light and dark unless the user explicitly asks to handle more modes. +- Do not infer brand, seasonal, or high-contrast modes from shadcn defaults. + +## Final Response + +After making changes, summarize: + +- Which variable collection was created or updated. +- Which modes exist. +- Which token groups were added or repaired. +- Whether values came from user-supplied CSS, verified shadcn defaults, or existing Figma variables. +- Any variables that were skipped, approximated, converted, or left unbound. +- Any components or frames that were bound to variables. +- Any follow-up needed from the user, especially missing `app/globals.css` or ambiguous custom tokens. + +Keep the summary concise and specific. Do not claim the system fully matches production code unless project CSS was available and all relevant variables were mapped. From edceb09b4bc08cdee28c08ad1c5dc36cfce16f72 Mon Sep 17 00:00:00 2001 From: Zachary BENSALEM Date: Sun, 19 Jul 2026 03:20:28 +0200 Subject: [PATCH 2/3] Register shadcn theme variables in router --- skills/figma-agent/figma-skill-router/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/skills/figma-agent/figma-skill-router/SKILL.md b/skills/figma-agent/figma-skill-router/SKILL.md index 1e243f0..89e9347 100644 --- a/skills/figma-agent/figma-skill-router/SKILL.md +++ b/skills/figma-agent/figma-skill-router/SKILL.md @@ -26,7 +26,7 @@ Use the request noun and verb to choose within the relevant group. | Discover and define | `design-brief-generator`, `build-from-prd`, `persona-builder`, `journey-map-builder`, `workshop-facilitator`, `affinity-mapping`, `sticky-synthesis`, `competitive-teardown`, `deck-from-outline` | | Content and brand | `content-inventory`, `content-tone-review`, `microcopy-generator`, `localization-readiness`, `brand-kit-asset-generator` | | Layout and construction | `container-layout-normalizer`, `responsive-breakpoint-check`, `spacing-scale-enforcer`, `figma-to-code-component`, `base-ui-primitive-composition`, `shadcn-component-structure`, `cva-variant-generator` | -| Components and libraries | `component-audit`, `component-naming-sync`, `library-health-report`, `follow-ds-guidelines`, `design-tokens-sync`, `legacy-styles-to-variables`, `apply-color-variables`, `color-token-format-normalizer`, `semantic-color-audit` | +| Components and libraries | `component-audit`, `component-naming-sync`, `library-health-report`, `follow-ds-guidelines`, `design-tokens-sync`, `legacy-styles-to-variables`, `apply-color-variables`, `color-token-format-normalizer`, `semantic-color-audit`, `shadcn-theme-variables` | | Review and quality | `accessibility-audit`, `heuristic-evaluation`, `design-crit`, `visual-consistency-check`, `states-completeness-check`, `site-launch-checklist`, `prototype-qa`, `animation-consistency-check` | | Prototypes and motion | `prototype-from-flow`, `wire-up-interactions`, `variable-driven-prototype`, `motion-spec-generator` | | Code, changes, and handoff | `code-connect-mapper`, `dev-handoff-prep`, `handoff-summary`, `token-tailwind-theme-sync`, `tailwind-class-order-check`, `design-change-diff`, `branch-review-summary` | @@ -35,7 +35,7 @@ Use the request noun and verb to choose within the relevant group. ## Tie-Breakers -Use `component-audit` for one set, `library-health-report` library-wide; `microcopy-generator` writes, `content-inventory` enumerates. `design-crit` is broad feedback, `heuristic-evaluation` usability, `accessibility-audit` access; `journey-map-builder` maps experience, `prototype-from-flow` plans screens. For unmatched requests: `design-brief-generator` (new) or `design-crit` (improve). +Use `shadcn-theme-variables` for creating or repairing semantic shadcn theme variables in Figma; use `token-tailwind-theme-sync` when Figma variables are already defined and code theme files need to catch up. Use `component-audit` for one set, `library-health-report` library-wide; `microcopy-generator` writes, `content-inventory` enumerates. `design-crit` is broad feedback, `heuristic-evaluation` usability, `accessibility-audit` access; `journey-map-builder` maps experience, `prototype-from-flow` plans screens. For unmatched requests: `design-brief-generator` (new) or `design-crit` (improve). ## Handoff From d1b7ffba55fc7eaf64162c63e4a6ab135b7f066d Mon Sep 17 00:00:00 2001 From: Zachary BENSALEM Date: Sun, 19 Jul 2026 04:11:05 +0200 Subject: [PATCH 3/3] Document shadcn theme variables skill --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 8872fb7..9f76653 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,7 @@ Skills are scoped for Figma design work: selection-first by default, evidence ti ## Catalogue -**56 skills** in [`skills/figma-agent/`](skills/figma-agent/). Grouped by job below; open a folder for the full `SKILL.md`. +**57 skills** in [`skills/figma-agent/`](skills/figma-agent/). Grouped by job below; open a folder for the full `SKILL.md`. ### Accessibility & usability @@ -67,6 +67,7 @@ Skills are scoped for Figma design work: selection-first by default, evidence ti | [`naming-convention-enforcer`](skills/figma-agent/naming-convention-enforcer/) | Renaming layers and components to a stated convention | | [`rename-layers-batch`](skills/figma-agent/rename-layers-batch/) | Bulk renaming with a simple rule or find/replace | | [`semantic-color-audit`](skills/figma-agent/semantic-color-audit/) | Catching raw palette usage where semantic tokens belong | +| [`shadcn-theme-variables`](skills/figma-agent/shadcn-theme-variables/) | Creating or repairing semantic shadcn theme variables in Figma | | [`spacing-scale-enforcer`](skills/figma-agent/spacing-scale-enforcer/) | Mapping arbitrary spacing onto the project scale | ### Components & code mapping