agentleFS
alexderzalexderz/agentic-toolbox/skills/astryx/SKILL.md

astryx

Skill5 starsChanged yesterdayMITView on GitHub

use this when a builder implements or reviews UI code in a product whose package.json depends on an @astryxdesign/* package, or whose approved LLD or mockups name Astryx; or when a designer or architect chooses a component library for a React web UI. it says how to get Astryx facts from the project's own CLI, how to build a page from Astryx templates, which delivery checks to run, and what wins on conflict. it loads beside the one language skill, ui-craft and modern-web-guidance, not in place of them. do not use for backend-only work, non-React UIs, or products that do not use or choose Astryx.

  • Installs packages

2 other projects use a version of this.

Adopted by

Most recently taken up by

The file

Show its rules and text

We split this skill into the rules it gives an agent

13 rules. About 0 are common, 7 are distinctive, and 6 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈7

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 6

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Never write a component name, prop, token, template or command from memory.

    line 28
  2. Distinctive:

    Do not load it for backend, tooling, config, tests-only, docs-only or copy-only turns, or for a UI that is not React.

    line 40
  3. Very specific:

    Never run the unscoped npx astryx: upstream states that it resolves to an unrelated npm package.

    line 66
  4. Distinctive:

    When a command prints a follow-up command, run it with your runner.

    line 71
  5. Very specific:

    Read the approved stories and mockups from ux-design, the LLD, and the nearest existing screen.

    line 96
  6. Very specific:

    Run template <name> <dir>, with <dir> inside the item's scope.

    line 101
  7. Distinctive:

    Keep the template's frame, gap and padding.

    line 103
  8. Very specific:

    Read a component's props with component <Name> before you write it.

    line 106
  9. Distinctive:

    Run these before you hand off, in order:

    line 114
  10. Distinctive:

    Run the project's build script.

    line 125
  11. Very specific:

    Run the ui-craft pass, unless the product's UI craft note records option 2 or 3.

    line 128
  12. Very specific:

    Never rows of every loaded skill and security-hardening apply throughout.

    line 135
  13. Distinctive:

    Record: If the product chooses Astryx, the architect records the choice and the exact version in the product's LLD.

    line 190

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 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

Astryx

Upstream: meta/astryx at cb2558efd0bd1e8988b8bf3d47fc1252343858a9, MIT, Copyright (c) 2026 Meta Platforms, Inc. This file is a first-party rewrite in this repository's words (MIT); no upstream text, plugin, CLI code or agent block is vendored. Pin and notes: SOURCES.md.

Astryx is a React design system: components, design tokens, themes, page and block templates, and a CLI, @astryxdesign/cli, that prints their docs. This skill has no scripts/. It runs no command of its own and uses no network; the commands below are ones you run in the product repo.

Actors. The builder implements or reviews UI code with Astryx. The designer and the architect consider Astryx when they choose a component library. The operator decides the actions this file marks as theirs. The manager receives rulings and asks.

Iron law

Get Astryx facts from the project's own CLI, at the project's version. Never write a component name, prop, token, template or command from memory. Read it from the CLI first.

When to load

  1. builder: load this skill when the turn implements or reviews UI code in a product repo and either condition holds:
    • the product's package.json lists an @astryxdesign/* package in dependencies, devDependencies or peerDependencies;
    • the product's approved LLD or approved mockups name Astryx.
  2. designer or architect: load this skill when the turn chooses a component library for a React web UI.
  3. Do not load it for backend, tooling, config, tests-only, docs-only or copy-only turns, or for a UI that is not React.
  4. This skill is not a language skill and replaces none. builder: load it beside the one language skill per the load-with list, ui-craft and modern-web-guidance. Designer and architect turns load no language skill.

How to read Astryx facts

Facts. The project's CLI is a devDependency, @astryxdesign/cli, at the same version as @astryxdesign/core. Find that version in package.json and the lockfile. The CLI documents itself; read its docs, not the files under node_modules/@astryxdesign/.

Pick the runner from the first row that matches:

Condition in the product repoRunner
package.json has an astryx scriptThe package manager's run command, such as npm run astryx -- <args>
@astryxdesign/cli is installed as a devDependencyThe package manager's exec runner, such as pnpm exec astryx <args> or npx @astryxdesign/cli <args>
@astryxdesign/core is installed, the CLI is notnpx @astryxdesign/cli@<core version> <args>, for reads only
  • The package manager is the one the lockfile names, per lang-js-ts.
  • Never run the unscoped npx astryx: upstream states that it resolves to an unrelated npm package. Use a runner from the table.
  • Adding the CLI as a devDependency is a dependency change. Follow the language skill's dependency rules and the LLD; until then, use the third row.
  • When a command prints a follow-up command, run it with your runner.

Reads, in the order to try them:

  1. search "<what you need>" — one ranked list across components, hooks, docs, templates and themes, each with its follow-up command. Narrow with --type component|hook|doc|template|theme.
  2. component <Name> — props, variants, examples and related block templates. component --list lists every component.
  3. hook <name> — one hook's docs.
  4. docs <topic> — reference docs, such as docs tokens, docs theme, docs layout. docs alone lists the topics.
  5. template --list; template <name> prints a template's source; template <name> --skeleton prints its layout skeleton.
  6. build "<idea>" — the template to start a page from and the parts it lacks.
  7. manifest --json — every command, option and response type of the installed version. <command> --help gives one command.

Output options: --json gives a typed envelope on every command except bare groups; --dense gives compact text for component and docs; --detail brief|compact|full sets list and docs size.

Build workflow

  1. Read the approved stories and mockups from ux-design, the LLD, and the nearest existing screen. They decide what to build.
  2. For each new page, run build "<idea>". Note the template it names and the parts it lacks.
  3. Run template <name> <dir>, with <dir> inside the item's scope. It writes the template's files into that folder. Its receipt names them.
  4. Keep the template's frame, gap and padding. Replace only its content.
  5. For each part the template lacks, run template <Block> for a block template, then component <Name> for each component you use.
  6. Read a component's props with component <Name> before you write it.
  7. For colors, spacing, radius and type, read docs tokens; for theming, docs theme. Use tokens, not literal values.
  8. On an existing page, keep its structure and change only what the item asks; do not re-scaffold it.

Delivery checks

Run these before you hand off, in order:

  1. Re-read each file you changed.
  2. In lines the item adds or changes, replace each raw <div> or <span> that an Astryx component or layout covers with that component. Read it with component <Name>.
  3. Replace each stylesheet import and each @apply you added with a component prop or a token. The Astryx and theme CSS imports that the project's setup requires stay.
  4. In lines the item adds or changes, replace each hard-coded hex color or px value with a token from docs tokens.
  5. Run the project's build script. Hand off that build and its output, not a description of the page. If the build fails, fix it or report the failure.
  6. Run the ui-craft pass, unless the product's UI craft note records option 2 or 3. Done evidence follows verify-before-done.

What wins on conflict

Never rows of every loaded skill and security-hardening apply throughout; this list orders the rest. The earlier item wins; name each conflict in your handoff.

  1. What is built: the approved mockups and stories (ux-design), the brief and the LLD. An Astryx template never adds scope: drop template parts that the mockups and stories do not ask for.
  2. How it is built: Astryx components, tokens and templates, read from the CLI.
  3. Visual rules where Astryx is silent: ui-craft. Where a ui-craft rule and an Astryx token or template disagree, the Astryx token or template wins. If the UI craft note records option 2 or 3, skip ui-craft.
  4. Platform features and code: between modern-web-guidance and the one language skill, such as lang-js-ts, follow modern-web-guidance's Precedence list.

Commands that change things outside the item

Each row states what the command changes, then what you may do.

CommandWhat it changesAllowed action
npm i -g @astryxdesign/cliInstalls a CLI for the whole computer. It prints update notices and keeps computer-level agent skill files in home-folder agent folders currentUse the project-local CLI. The operator may choose it for their own computer
astryx init --userWrites ~/.agents/skills/astryx/SKILL.md and links or copies it into other agents' skill folders, such as ~/.claude/skillsUse the project-local CLI. The operator may choose it for their own computer
astryx init, astryx init --all, --features with agents, or astryx init --remove-agentsWrites, or removes, a managed Astryx block in the repo's AGENTS.md and its Claude file (CLAUDE.md, else .claude/CLAUDE.md), and an import line in GEMINI.md; --remove-agents also edits other agent files. In a repo governed by this SDLC, those files are agent textRun astryx init --features theme,template; its theme feature writes theme.template.ts, inside the item's scope. If the product wants the agent block, make it its own reviewed item
astryx gap-report ... --confirm-publicFiles a public GitHub issue with the user's gh login: a public postAsk the operator first per Asking the operator. Without --confirm-public, no public handler runs and no GitHub issue is filed; handlers that the project or its integrations configure as internal always run. You may prepare the report and put it in the ask, with every destination the output lists
swizzle <Name>, upgrade --apply, template <name> <dir>, theme commands that add, switch or build a themeEdit or add project files: ejected component source, codemods, scaffolded pages, theme files. upgrade --apply also runs the hooks.postCodemod commands in astryx.configRun them only on files inside the item's scope
The hosted MCP server, https://astryx.atmeta.com/mcp (tools search, get)Sends your query to a public remote service. Connecting it adds an MCP server to the agent's configurationPrefer the local CLI. Send only generic component questions; never private code, names or data. The operator may choose to connect it
The upstream Claude Code or Codex pluginA marketplace install of agent text this repo has not reviewedNever marketplace-install it from this skill. Load this skill instead

Choosing Astryx at design time

designer and architect: apply this section; the build workflow and delivery checks are the builder's. Give these facts in the list of component-library options; this skill does not recommend Astryx for every product.

  1. Fit. Astryx is a candidate when the product UI is React 19 or later. react and react-dom 19 or later, and @stylexjs/stylex, are peer dependencies of @astryxdesign/core.
  2. What it offers. Over 150 accessible components, page and block templates (dashboards, settings, forms, detail pages), design tokens, dark mode and brand theming through CSS custom properties, and seven ready-made themes. Styles are pre-built CSS imports: no build plugin. Consumers may override with className using Tailwind, CSS modules or plain CSS.
  3. Status. Astryx is Beta. The chart packages (@astryxdesign/vega, @astryxdesign/charts) are published only under the @canary tag, and @astryxdesign/lab is not published.
  4. Cost. Adopting it adds npm dependencies: @astryxdesign/core, a theme package such as @astryxdesign/theme-neutral, and @stylexjs/stylex, plus @astryxdesign/cli as a devDependency. Follow the product's dependency rules.
  5. Record. If the product chooses Astryx, the architect records the choice and the exact version in the product's LLD. That version is the one the builder's CLI reads at.
  6. Reading before a project exists. The architect reads the current stable release with npm view @astryxdesign/core version (the latest tag, never @canary) and records it in the LLD. Every read uses npx @astryxdesign/cli@<that version> <read>. The hosted MCP row above applies to remote questions.
  7. License. MIT.

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.