agentleFS
robritacca-dotcomrobritacca-dotcom/rift-ds/.claude/skills/new-figma-component/SKILL.md

new-figma-component

Skill9 starsChanged todayMITView on GitHub

Build a library component into the Rift DS Figma kit (a component set bound to the kit's variables, one sticker sheet and a page in the kit's recipe) and map its frame in website/src/data/figma-nodes.json. Runs apart from new-component, so the code and the Figma work can be split. Use when asked to add a component to Figma, build the Figma side of a component, or draw [Name] in the kit.

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If the component does not exist in src/components/registry.json (or src/chat/registry.json for a chat widget) yet, stop: the code comes …

    line 19
  2. Distinctive:

    After swapping an icon in an instance, re-apply the glyph's fill.

    line 41
  3. Distinctive:

    Never edit text inside an icon instance by index: a TEXT search also finds the glyphs.

    line 42

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

new-figma-component

Build one library component into the Rift DS Figma kit and wire its frame back to the site. The code already exists: this skill draws it, it never changes it.

When invoked

Use when asked to add a component to the Figma kit, build the Figma side of a component, or draw a component in the kit. It is the design half of adding a component, kept separate from the new-component skill so the two can run in different sessions. A component in code with no frame fails scripts/validate-figma-nodes.mjs, which runs before every root build, Storybook and verify, so until this skill runs for it nothing ships.

If the component does not exist in src/components/registry.json (or src/chat/registry.json for a chat widget) yet, stop: the code comes first, through new-component. Figma never leads the code.

Before the first Figma call

  • Load the Figma connector's figma-use skill (the get_figma_skill tool serves it when no Figma plugin is installed) before any use_figma call. It owns the plugin API and its traps.
  • Open a session on the kit: the file key is the path segment of FIGMA_FILE_URL in scripts/brand.mjs. Call create_session with it and a one-line task, and reuse the session id on every later call.
  • Never write a file key, node id or URL from memory. Find nodes by name with a read-only use_figma script, and derive every URL from SITE_URL, STORYBOOK_URL, REPOSITORY_URL and AUTHOR_URL in scripts/brand.mjs.

The kit's conventions

This section is the one home of how the kit is built. The figma-parity and new-figma-template skills point here rather than restating it. The site's /docs/figma page is the kit's public description and states some of these conventions for visitors (its source is website/src/app/docs/figma/), so a change to a convention it describes moves that page too.

Variables. Three collections. Primitives holds each preset's raw values and is hidden. Theme has one mode per preset the file carries (the default theme first) and holds the light and dark colour layers, the dimensions and the fonts. Mode (Light, Dark) holds the semantic colours, and it is the only collection components bind colour to. Every fill, stroke, radius, gap and padding binds to a variable named after its token, so a theme or mode switch at the page changes everything. A value with no token is a sign the code has one you missed: look it up in src/tokens/values.json before reaching for a raw number.

  • Never pin a Theme or Mode on a frame. Frames stay on Auto, so the page's setting drives the whole page. The Themes page's theme cards and the Cover's marketing frames are the only sanctioned pins.
  • Never bake a fade as a colour gradient: it ignores Light and Dark. Fade with an alpha-only gradient mask over bound-colour layers.
  • A concentric radius (a shell around a control, such as the composer around its send button) is the one place a hand-set number beats a token, because Figma cannot add the inset and border to the inner radius. Pick the number that fits the page's theme.

Component sets. Variant properties follow the props in website/public/schema/components/<slug>.json: one property per enum prop (variant, tone, size and the rest, named and valued as in code), and a boolean property per boolean state prop such as disabled. Hover, pressed and focus are CSS states, not props, so they are a State property at most, never a prop the code lacks. Text and instance-swap properties carry the label and the icons. The set's description holds the registry description, the import line and the prop mapping (Code Connect is unavailable on the kit's plan, so the description is where a designer finds the code).

  • Bind component properties only to the component's own layers, never inside a nested instance (it throws).
  • A text property shares one value across every variant, so text that differs by status stays unbound.
  • After swapping an icon in an instance, re-apply the glyph's fill.
  • Never edit text inside an icon instance by index: a TEXT search also finds the glyphs.
  • A body the consumer fills (a popover's, a field's) is a slot made with createSlot().
  • Compose the kit's own components (a Button inside a Dialog is a Button instance), the same way the code composes them. A sub-component the set needs goes in the page's Building blocks panel.
  • Icons are instances from the Icons page. A glyph the code uses that the page lacks is added there, never drawn locally.

One sticker sheet. Each component gets its set and one sticker sheet showing the meaningful combinations in the default theme, Light. Never repeat artboards per theme or mode: the variables already prove the switch.

The page recipe. Every component gets its own page, named after the component's label, set to the Theme and Mode every other component page uses (read them off a neighbour), with the same page background. On it, one auto-layout wrapper frame named after the component holds:

  1. A header card: a top bar with the Rift DS mark on the left, linked to SITE_URL, and meta links on the right (Rift DS, GitHub and the author, as underlined secondary text linking to SITE_URL, REPOSITORY_URL and AUTHOR_URL); then the title in the Display/2 style, the registry description, and an "In Figma and code" status pill.
  2. A links row: two Button instances cloned from the pair on an existing component page (Primary and Neutral, Compact, with the Rift DS and Storybook marks leading and an arrow trailing), never text links. Each gets an on-click URL reaction and the same URL on its label's text hyperlink, or a click in design mode follows the clone's old link: SITE_URL/components/<slug> and STORYBOOK_URL followed by the component's Storybook path. Take that path from the storybookPath its docs page passes to PageLinks (usually /?path=/docs/components-<name lowercased>--docs, but a chat widget's sits under chat-), and check it against the deployed Storybook's index.json.
  3. Columns: the sticker sheet panel on the left; the main component panel on the right, with a Building blocks panel under it when the set has sub-components.

Colours: the wrapper takes the page background token; the header, the links row and every panel take the primary container fill with the container border as an outline. Sticker sheets and component sets have no fill, and the right column is unfilled. A standalone panel component keeps its own surface. Icon components never sit on a component page.

Page order: Cover, a divider, Colour, Icons, Typography, Themes, a second divider, then every component page in alphabetical order. Re-sort after adding a page.

Demo content follows the code's own defaults and the content guide: fictional names, avatars off unless the component exists to show one.

Instructions

1. Read the component in code

  • Its registry entry (label, slug, category, description) and its schema in website/public/schema/components/<slug>.json (every prop, its type, its default).
  • Its CSS, for the tokens each part uses, and its stories, for the combinations worth showing.
  • Its rendered page: open SITE_URL/components/<slug> (or the local dev server) in the built-in browser and screenshot the default theme. That picture is the target.

2. Read the kit

With a read-only use_figma script: the page list and order, the nearest sibling's page (same family) as the layout reference, the link-button pair to clone, and the variables the component's tokens map to. Note any token with no variable; step 3 adds it before drawing.

3. Build

In small use_figma steps, checking each with get_screenshot before the next:

  1. Any missing variable, added to the right collection with a value for every mode, from src/tokens/values.json.
  2. The component set, its properties and its description.
  3. The sticker sheet.
  4. The page in the recipe, placed in alphabetical order.

4. Check fidelity

Screenshot the main variant beside the site's render in the default theme. Measure what differs (padding, radius, type, icon size) and fix it in Figma. Then switch the page's Theme and Mode once to confirm everything follows, and set them back.

5. Map the frame

Add the component's slug to components in website/src/data/figma-nodes.json, in alphabetical order, with the wrapper frame's node id in URL form (12-345, the colon written as a hyphen). Run node scripts/validate-figma-nodes.mjs, then open the component's docs page and confirm its Figma link lands on the frame.

6. Report

The page, the set's variant properties and the sticker sheet, with a screenshot. Name any prop the kit could not express and any token you had to add. Nothing is committed: the map change waits for the owner, like any other.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.