@rolemodel/optics 2.5.0 → 2.6.0

package/.agents/skills/github-release/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: github-release
+description: Draft, write, and publish an Optics release on GitHub — checks the version bump, resolves the previous tag, generates notes from the release.yml categories, adds a plain-language line under each PR, and publishes, which ships the package to npm and GitHub Packages and redeploys the docs site. Use this whenever the user mentions cutting a release, bumping the version, drafting or writing release notes, publishing to npm, "what's going out", or updating the CHANGELOG for a release — even if they don't say the words "release notes".
+---
+
+# Optics Release
+
+Adapted from the `github-release` skill in RoleModel/bgea_volunteer_care.
+
+A release is two steps, with a person in between:
+
+1. **Draft** — check the version, write the notes, save an unpublished draft.
+2. **Publish** — only once the user says go. Publishing ships the package.
+
+Keep them apart. Publishing a release fires `deploy-to-npm.yml` and `deploy-to-ghp.yml`, which
+publish `@rolemodel/optics` to npm and GitHub Packages. An npm version number can never be
+reused, so a mistake means another release.
+
+|          |                                                                 |
+| -------- | --------------------------------------------------------------- |
+| Tag      | `v2.5.0` (semver, lowercase `v`)                                |
+| Title    | Same as the tag                                                 |
+| Baseline | The latest published release                                    |
+| Ships    | The tip of `main`                                               |
+| Notes    | The categories in `.github/release.yml`, one line under each PR |
+
+---
+
+## Phase 1 — Draft
+
+### 1. Check the version bump is on main
+
+The version is bumped in a pull request, not at release time. Before drafting, `main` must have:
+
+- `package.json` `"version"` set to the new number
+- The three `.storybook/assets/*.html` example pages pointing at the new CDN version
+- A `## [X.Y.Z] - YYYY-MM-DD` section at the top of `CHANGELOG.md`
+
+```bash
+git fetch origin --tags
+git show origin/main:package.json | grep '"version"'
+grep -o 'optics@[0-9.]*' .storybook/assets/*.html
+gh release list --limit 3
+```
+
+If the version on `main` is not higher than the latest release, stop. Offer to open the bump PR
+instead. Pick the number from what changed: breaking changes are a major bump, anything new is a
+minor bump, and fixes only are a patch.
+
+### 2. Get the change list
+
+```bash
+gh api repos/RoleModel/optics/releases/generate-notes \
+  -f tag_name=v<new> -f target_commitish=main -f previous_tag_name=<latest release tag> \
+  --jq .body
+```
+
+GitHub sorts PRs into the `.github/release.yml` categories by label. Act on:
+
+- **Unlabeled Changes (please categorize these)** — label each PR on GitHub, then generate again.
+  Don't ship this heading.
+- **A PR listed twice** — GitHub puts a PR in the first category that matches. Move it only if
+  that category is wrong for what it did.
+- **Commits with no PR** — `git log <latest tag>..origin/main --oneline` shows them. Mention one
+  only if it changed the shipped CSS.
+
+Report what you found, for example "6 PRs: 1 component, 1 dependency, 4 docs; 1 unlabeled".
+
+### 3. Write a line under each PR
+
+The readers are developers who use Optics in their apps. Under each PR, add one indented line
+that says what changed for them: the class, token, or variable name, and what it now does. The
+PR body's **Why?** and **What Changed** sections are the best source.
+
+| Weak                   | Strong                                                                                       |
+| ---------------------- | -------------------------------------------------------------------------------------------- |
+| Update icon libraries  | The icon library addons point at the latest versions, so every icon in each set is available |
+| Fix documentation site | Fixed the sidebar examples and the switch syntax example on the documentation site           |
+
+- Dependency PRs: say whether they change the shipped CSS. They usually don't.
+- A PR with nothing to explain (an admin or repo setting) can stand without a line.
+- Keep GitHub's **New Contributors** and **Full Changelog** lines.
+
+### 4. Match the CHANGELOG
+
+The `CHANGELOG.md` section for this version should list the same PRs in the same categories.
+If it is missing one, say so. The fix is a follow-up PR, not an edit during the release.
+
+### 5. Create the draft
+
+```bash
+gh release create v<new> --draft --title "v<new>" --notes-file <path> --target main
+```
+
+A draft creates no tag and fires no workflow, so it is safe to redo (`gh release edit`,
+`gh release delete`). Show the user the URL and print the full notes in the chat. Then stop.
+
+---
+
+## Phase 2 — Publish
+
+Only after the user says to publish.
+
+```bash
+gh release edit v<new> --draft=false --latest
+```
+
+Then check the three release workflows:
+
+```bash
+gh run list --workflow deploy-to-npm.yml --limit 1
+gh run list --workflow deploy-to-ghp.yml --limit 1
+gh run list --workflow publish-storybook.yml --limit 1
+```
+
+- `publish-storybook.yml` runs on `release: created`. GitHub does not send `created` when a
+  draft is published, so the docs site likely did not redeploy. Run it:
+  `gh workflow run publish-storybook.yml --ref main`
+- `deploy-to-npm.yml` publishes with npm Trusted Publishing (OIDC), so there is no token. If it
+  fails with `E404` or `ENEEDAUTH`, the trusted publisher on npmjs.com (package Settings → Trusted
+  Publisher) doesn't match this repo and workflow file. Someone with npm admin access fixes it
+  there. Never switch back to an `NPM_TOKEN` that bypasses 2FA.
+- To retry, `gh run rerun <run id> --failed` builds from the tag with the workflow file as it was
+  at the tag. If the workflow was fixed after the tag, use
+  `gh workflow run deploy-to-npm.yml --ref main` instead, and only if `main` has no CSS changes
+  since the tag.
+
+Confirm the package is out:
+
+```bash
+npm view @rolemodel/optics version
+```
+
+Finally, give the user the notes as a copyable block for Slack, without the Full Changelog link.
+
+---
+
+## Guardrails
+
+- **Never publish without the user's go-ahead.** It ships a package version that can't be taken
+  back.
+- **Never release from a branch.** The target is always `main`, after the bump PR has merged.
+- **Never invent a PR or what it did.** If a PR body is thin, say the line is a guess and ask.

package/.github/workflows/linting.yml

@@ -29,6 +29,8 @@ jobs:
         run: yarn lint:css
       - name: Run Prettier
         run: yarn prettier-check
+      - name: Run Tests
+        run: yarn test
       - name: Build CSS
         run: yarn build:css
       - name: Build Tokens

package/.prettierignore

@@ -3,5 +3,8 @@ tools/templates
 .yarn/*
 optics-design-system.code-workspace
 
+# Claude Code settings and worktrees (each worktree is a full checkout)
+.claude/
+
 # Generated docs
 llms-docs

package/CHANGELOG.md

@@ -4,6 +4,53 @@ All notable changes to this project will be documented in this file.
 
 This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.6.0] - 2026-10-21
+
+### Theme Token Changes
+
+- Add an opt-in OKLCH color build by @Jeremy-Walton in https://github.com/RoleModel/optics/pull/368
+  - A new `optics-oklch.css` build (and one per icon set, such as `optics-oklch+lucide_icons.css`) defines every color token with `oklch()`. To switch, replace `optics` with `optics-oklch` in your import. The HSL build stays the default and is unchanged, and `core/tokens/base_tokens.css` still includes the color tokens for apps that import it directly. Apps can also run the new `optics-check-contrast` command in CI to check their theme's text contrast. See [OKLCH Colors](https://docs.optics.rolemodel.design/?path=/docs/overview-oklch-colors--docs) and [Contrast Checker](https://docs.optics.rolemodel.design/?path=/docs/tools-contrast-checker--docs)
+
+### Dependencies
+
+- Update transitive dependencies to resolve Dependabot alerts by @Jeremy-Walton in https://github.com/RoleModel/optics/pull/367
+  - Development dependencies were updated in the lockfile. It does not affect the shipped CSS.
+
+### Repository Changes
+
+- Add an opt-in OKLCH color build by @Jeremy-Walton in https://github.com/RoleModel/optics/pull/368
+  - Added tests for the contrast checker, which `yarn test` and the Linting CI workflow now run. The docs build now creates the llms docs before Storybook.
+
+### Documentation Changes
+
+- Add an opt-in OKLCH color build by @Jeremy-Walton in https://github.com/RoleModel/optics/pull/368
+  - Added an [OKLCH Colors](https://docs.optics.rolemodel.design/?path=/docs/overview-oklch-colors--docs) page, a Tools section with the [Contrast Checker](https://docs.optics.rolemodel.design/?path=/docs/tools-contrast-checker--docs) page, an HSL / OKLCH toggle in the documentation site toolbar, and an OKLCH template on the Color Scale page.
+
+**Full Changelog**: https://github.com/RoleModel/optics/compare/v2.5.1...v2.6.0
+
+## [2.5.1] - 2026-10-01
+
+### Component Changes
+
+- Update table classes for consistency by @Jeremy-Walton in https://github.com/RoleModel/optics/pull/364
+  - The table modifiers now put the modifier name before its value: `.table--layout-auto`, `.table--layout-fixed`, `.table--density-default`, `.table--density-comfortable`, `.table--density-compact`, `.table--striped-even` and `.table--striped-odd`. The old names (such as `.table--comfortable-density`) still work, so no change is needed.
+
+### Dependencies
+
+- Bump brace-expansion from 1.1.16 to 1.1.21 by @dependabot[bot] in https://github.com/RoleModel/optics/pull/361
+  - A development dependency was updated in the lockfile. It does not affect the shipped CSS.
+- Bump undici from 7.29.0 to 7.30.0 by @dependabot[bot] in https://github.com/RoleModel/optics/pull/362
+  - A development dependency was updated in the lockfile. It does not affect the shipped CSS.
+
+### Repository Changes
+
+- Add a github-release skill by @dallasbpeters in https://github.com/RoleModel/optics/pull/360
+  - Added a Claude Code skill that runs the same release steps every time.
+- Publish to npm with Trusted Publishing by @dallasbpeters in https://github.com/RoleModel/optics/pull/363
+  - The package is now published to npm with Trusted Publishing, so no npm token is stored. Each published version now has provenance, which shows the GitHub workflow that built it.
+
+**Full Changelog**: https://github.com/RoleModel/optics/compare/v2.5.0...v2.5.1
+
 ## [2.5.0] - 2026-09-30
 
 ### Component Changes

package/README.md

@@ -40,6 +40,8 @@ You can add this import to the top of your root level `css` file.
 @import '@rolemodel/optics/dist/css/optics.min.css'; /* If you want a single file with all the styles in it. */
 ```
 
+An OKLCH build is also available. See [OKLCH Colors](https://docs.optics.rolemodel.design/?path=/docs/overview-oklch-colors--docs).
+
 ### Importing without a compiler
 
 To use Optics without compilation, use a CDN like [jsDelivr](https://www.jsdelivr.com/) or [unpkg](https://unpkg.com/).
@@ -58,6 +60,20 @@ Add a link in your HTML head or an `@import` to the top of your root level `css`
 
 Note: You can use this method to use Optics with [CodePen](https://codepen.io/). In a CodePen project, go to `Settings > CSS`, find the section for adding external stylesheets, and add the CDN link as a resource.
 
+### Checking theme contrast
+
+After customizing your theme, add `optics-check-contrast` to your CI to check that text on every color scale step passes WCAG AA:
+
+```json
+{
+  "scripts": {
+    "check-contrast": "optics-check-contrast app/assets/stylesheets/theme.css"
+  }
+}
+```
+
+See [Contrast Checker](https://docs.optics.rolemodel.design/?path=/docs/tools-contrast-checker--docs) for options.
+
 ## Documentation
 
 We use [Storybook](https://storybook.js.org/docs/html/get-started/introduction) as a way to provide informative and interactive documentation.

package/build_token_json.js

@@ -132,7 +132,8 @@ try {
       .filter((directoryEntry) => directoryEntry.isFile() && directoryEntry.name !== 'index.css')
       .forEach((directoryEntry) => {
         const fileContents = fs.readFileSync(`${source}/${directoryEntry.name}`)
-        const matches = fileContents.toString().match(/^\s*--.*?(?=;)/gm)
+        // Import-only files like base_tokens.css declare no variables.
+        const matches = fileContents.toString().match(/^\s*--.*?(?=;)/gm) ?? []
         matches.forEach((match) => {
           const [key, value] = match.split(':')
           variables = addToJson(splitKey(key.trim()), variables, value.trim())

package/dist/README.md

@@ -40,6 +40,8 @@ You can add this import to the top of your root level `css` file.
 @import '@rolemodel/optics/dist/css/optics.min.css'; /* If you want a single file with all the styles in it. */
 ```
 
+An OKLCH build is also available. See [OKLCH Colors](https://docs.optics.rolemodel.design/?path=/docs/overview-oklch-colors--docs).
+
 ### Importing without a compiler
 
 To use Optics without compilation, use a CDN like [jsDelivr](https://www.jsdelivr.com/) or [unpkg](https://unpkg.com/).
@@ -58,6 +60,20 @@ Add a link in your HTML head or an `@import` to the top of your root level `css`
 
 Note: You can use this method to use Optics with [CodePen](https://codepen.io/). In a CodePen project, go to `Settings > CSS`, find the section for adding external stylesheets, and add the CDN link as a resource.
 
+### Checking theme contrast
+
+After customizing your theme, add `optics-check-contrast` to your CI to check that text on every color scale step passes WCAG AA:
+
+```json
+{
+  "scripts": {
+    "check-contrast": "optics-check-contrast app/assets/stylesheets/theme.css"
+  }
+}
+```
+
+See [Contrast Checker](https://docs.optics.rolemodel.design/?path=/docs/tools-contrast-checker--docs) for options.
+
 ## Documentation
 
 We use [Storybook](https://storybook.js.org/docs/html/get-started/introduction) as a way to provide informative and interactive documentation.

package/dist/css/components/table.css

@@ -81,28 +81,37 @@
   }
 
   /* Layout Modifiers */
+  /* The *-layout names are kept for backwards compatibility */
+  &.table--layout-auto,
   &.table--auto-layout {
     table-layout: auto;
   }
 
+  &.table--layout-fixed,
   &.table--fixed-layout {
     table-layout: fixed;
   }
 
   /* Table Density Modifiers */
+  /* The *-density names are kept for backwards compatibility */
+  &.table--density-default,
   &.table--default-density {
     --__op-table-cell-height: var(--_op-table-cell-height-default);
   }
 
+  &.table--density-comfortable,
   &.table--comfortable-density {
     --__op-table-cell-height: var(--_op-table-cell-height-comfortable);
   }
 
+  &.table--density-compact,
   &.table--compact-density {
     --__op-table-cell-height: var(--_op-table-cell-height-compact);
   }
 
   /* Striped Modifiers */
+  /* The *-striped names are kept for backwards compatibility */
+  &.table--striped-even,
   &.table--even-striped {
     tbody tr:nth-child(even) {
       background-color: var(--op-color-neutral-plus-seven);
@@ -110,6 +119,7 @@
     }
   }
 
+  &.table--striped-odd,
   &.table--odd-striped {
     tbody tr:nth-child(odd) {
       background-color: var(--op-color-neutral-plus-seven);

package/dist/css/core/tokens/base_color_tokens.css

@@ -0,0 +1,74 @@
+:root {
+  /* Color HSLs
+    A theme comprised of a primary, neutral, warning, danger, info, and notice colors.
+  */
+
+  /* Basic Colors */
+
+  /**
+  * @tokens Basic Colors
+  * @presenter Color
+  */
+  --op-color-white: hsl(0deg 100% 100%);
+  --op-color-black: hsl(0deg 0% 0%);
+
+  /**
+  * @tokens Primary Colors
+  * @presenter Color
+  */
+  --op-color-primary-h: 216;
+  --op-color-primary-s: 58%;
+  --op-color-primary-l: 48%;
+
+  /**
+  * @tokens Neutral Colors
+  * @presenter Color
+  */
+  --op-color-neutral-h: var(--op-color-primary-h);
+  --op-color-neutral-s: 4%;
+  --op-color-neutral-l: var(--op-color-primary-l);
+
+  /**
+  * @tokens Alerts Warning Colors
+  * @presenter Color
+  */
+  --op-color-alerts-warning-h: 47;
+  --op-color-alerts-warning-s: 100%;
+  --op-color-alerts-warning-l: 61%;
+
+  /**
+  * @tokens Alerts Danger Colors
+  * @presenter Color
+  */
+  --op-color-alerts-danger-h: 0;
+  --op-color-alerts-danger-s: 99%;
+  --op-color-alerts-danger-l: 76%;
+
+  /**
+  * @tokens Alerts Info Colors
+  * @presenter Color
+  */
+  --op-color-alerts-info-h: 216;
+  --op-color-alerts-info-s: 58%;
+  --op-color-alerts-info-l: 48%;
+
+  /**
+  * @tokens Alerts Notice Colors
+  * @presenter Color
+  */
+  --op-color-alerts-notice-h: 130;
+  --op-color-alerts-notice-s: 61%;
+  --op-color-alerts-notice-l: 64%;
+
+  /* Shadows */
+
+  /**
+  * @tokens Shadows
+  * @presenter Shadow
+  */
+  --op-shadow-x-small: 0 1px 2px hsl(0deg 0% 0% / 3%), 0 1px 3px hsl(0deg 0% 0% / 15%);
+  --op-shadow-small: 0 1px 2px hsl(0deg 0% 0% / 3%), 0 2px 6px hsl(0deg 0% 0% / 15%);
+  --op-shadow-medium: 0 4px 8px hsl(0deg 0% 0% / 15%), 0 1px 3px hsl(0deg 0% 0% / 3%);
+  --op-shadow-large: 0 6px 10px hsl(0deg 0% 0% / 15%), 0 2px 3px hsl(0deg 0% 0% / 3%);
+  --op-shadow-x-large: 0 8px 12px hsl(0deg 0% 0% / 15%), 0 4px 4px hsl(0deg 0% 0% / 3%);
+}