mcpField
O
optics-context

optics-context

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

About optics-context

A coding skill for teams using RoleModel's Optics CSS design system. It guides developers to inspect installed tokens and components, reuse existing styles, and make scoped overrides rather than duplicating components.

Key features

  1. 01Inspect installed design tokens
  2. 02Find available CSS components
  3. 03Reuse project classes and BEM blocks
  4. 04Override components in designated files
  5. 05Apply tokens instead of literal values
  6. 06Check theme and dark-mode behavior

Use cases

  1. 01Select a valid Optics token for a style
  2. 02Check whether a component already exists
  3. 03Customize an Optics component across an app
  4. 04Avoid malformed token names and partial theme overrides

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/rolemodel/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

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/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/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