mcpField
O
optics-context

optics-context

github.com/rolemodelDesign & UI780 installsUpdated 2d ago
Repository

About optics-context

optics-context is an agent skill for working with RoleModel’s Optics CSS design system. It directs developers to inspect the installed package for current tokens and components, and gives guidance for composing styles and theming.

Key features

  1. 01Find tokens and components in the installed package
  2. 02Prefer existing Optics components
  3. 03Reuse project classes before adding components
  4. 04Use design tokens instead of literal values
  5. 05Guidance for overrides and theming

Use cases

  1. 01Checking valid token names before writing CSS
  2. 02Choosing an existing component for a view
  3. 03Overriding Optics components across an app

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/rolemodel/skills --skill optics-context

After installing, type/optics-contextin Claude Code to confirm it loaded.

Bundled filesreferences/theming.md

Details

From the project README

Optics

Optics is RoleModel's CSS design system, published as @rolemodel/optics. The installed package is the source of truth for which components and tokens exist. Read it instead of recalling names from memory, since tokens change between versions.

  • Tokens: node_modules/@rolemodel/optics/dist/tokens/tokens.json (or the CSS under dist/css/core/tokens/ in older versions)
  • Components: node_modules/@rolemodel/optics/dist/css/components/*.css
  • Version: the @rolemodel/optics entry in package.json
  • Docs: https://docs.optics.rolemodel.design
  • Docs for agents: https://docs.optics.rolemodel.design/llms.txt (markdown index; component pages show the HTML for each variant). It covers the latest release, so check names against the installed package.

Before writing CSS

  1. Use an Optics component if one fits. Check dist/css/components/ for the block and its modifiers.
  2. Reuse a project class if one exists. Search app/assets/stylesheets/.
  3. Write a new component only when neither fits: one block per file in app/assets/stylesheets/components/{block}.css, named and nested per the bem-structure skill.

To change how an Optics component looks across the app, override it in app/assets/stylesheets/components/optics-overrides/{component}.css. Don't fork it into a new block.

Optics also ships utility classes (.flex, .gap-sm, and the rest of dist/css/core/utilities.css). RoleModel strongly discourages them in views: style through a BEM block or element instead.

Tokens, not literals

Every color, spacing, font, radius, border, and shadow value comes from a token.

Instead ofUse
#fff, rgb(...), whitevar(--op-color-background), var(--op-color-primary-base)
padding: 12pxpadding: var(--op-space-small)
border: 1px solid #dddborder: var(--op-border-width) solid var(--op-color-border)
box-shadow: 0 1px 3px rgba(...)box-shadow: var(--op-shadow-small)

Put text on a colored surface with that surface's matching on- token: --op-color-primary-on-base on --op-color-primary-base, --op-color-primary-on-plus-two on --op-color-primary-plus-two.

When no token fits, define a project token with the app's own prefix (--ya-color-brand-accent for "Your App"). Never add new names under --op-.

Gotchas

  • Malformed names fail silently. var(--op_color_primary_base), var(--color-primary-base), and var(--op-primary-color-base) all resolve to nothing and the property falls back with no error. Check the name against tokens.json.
  • Plus and minus flip in dark mode. Each step is a light-dark() pair. In light mode plus-* is lighter and minus-* darker; in dark mode it reverses, so plus-max goes from the lightest step to the darkest. Pick a step by its role against the background, not by "lighter" or "darker", and check both values in scale_color_tokens.css.
  • Optics has more components than you'd guess. Besides btn and card it ships avatar, badge, tag, alert, modal, table, tab, switch, spinner, sidebar, side-panel, text-pair, segmented-control, and others. Look in dist/css/components/ before writing any block, and don't hedge with "if your Optics version has it" when you can check. Writing your own block under an Optics name (a new .avatar { … }) doesn't create a separate component: it merges into Optics' rules and changes every avatar in the app. Use the Optics block, and put changes in components/optics-overrides/{component}.css or a project modifier.
  • Partial theme overrides break the scale. See references/theming.md before changing any --op-color-* value.

Theming

To change brand colors, fonts, radius, or a color scale for the whole app, read references/theming.md.

Comments

Markdown supported