feat(tokens): updated color docs and ring

[najlaskr]

Summary

This PR aims to solve two problems:

1. The USAGE.md token reference and the docs site token guide documented different things without a clear source of truth
2. While kumo-ring was introduced as a lighter border variant of kumo-line for flat surfaces, the name conflicted with Tailwind's built-in ring utility

Changes

• Aligned content in USAGE.md and in colors.mdx so both describe the same tokens with consistent descriptions
• Renamed kumo-ring to kumo-hairline across all kumo components and docs. No colour changes done here so there shouldn't be any visual changes done
• Fixed a typo in the kumo-recessed dark mode value in config.ts (oklch(12% 0 0) → oklch(15% 0 0))

---

• Reviews
  • bonk has reviewed the change
  • automated review not possible because: no access to bonk
• Tests
  • Tests included/updated
  • Automated tests not possible - manual testing has been completed as follows:
  • Additional testing not necessary because:

[geoquant]

/bonk review

[stritt]

/bonk review please

[pkg-pr-new]

npm i https://pkg.pr.new/@cloudflare/kumo@355

commit: 4f7ed26

[ask-bonk]

Thanks for this comprehensive cleanup PR! The token rename from kumo-ring to kumo-hairline is well-executed and addresses the Tailwind naming conflict effectively.

Summary

What works well:

1. Comprehensive rename - The kumo-ring → kumo-hairline change is consistently applied across all 33 files including components, themes, Figma generators, documentation, and lint rules.

2. Documentation alignment - USAGE.md and colors.mdx now share consistent token categorization and descriptions, creating a single source of truth.

3. Changeset accuracy - Properly identifies this as a patch change for both packages.

4. Token descriptions - The new descriptions in the Borders & Rings section clearly explain the distinction between kumo-hairline (for flat surfaces without shadow) and kumo-line (for elevated surfaces with shadow).

Minor Notes

1. PR description typo - The description mentions the recessed dark token fix as oklch(15% 0 0) → oklch(12% 0 0), but the actual change goes the other direction (12% → 15%). The code change is correct and consistent between config.ts and theme-kumo.css, just the description has the direction reversed.

2. Unmentioned fix - The theme-kumo.css also includes a fix to kumo-fill-hover dark mode (changed from --color-neutral-700 to --color-neutral-800). This appears to be a legitimate fix (making the fallback value match the variable), but wasn't mentioned in the changeset. Consider adding it to the changeset for completeness.

Overall, this is a solid PR that improves consistency and avoids naming conflicts. Approving with minor suggestions above.

[ask-bonk]

I've completed the review of PR #355. Here's a summary of my findings:

Review Summary

✅ What's Working Well

1. Comprehensive token rename - The kumo-ring → kumo-hairline change is consistently applied across all 33 files including:

   • 12 component files
   • 2 theme CSS files (kumo + fedramp)
   • Figma generators and parsers
   • Component registry metadata
   • Documentation (USAGE.md, colors.mdx)
   • AGENTS.md files and lint rules

2. Documentation alignment - USAGE.md and colors.mdx now share consistent token categorization (Surface Hierarchy, Brand, Semantic Status Colors, Text Colors, Borders & Rings)

3. Proper changeset - Correctly identifies patch changes for both packages

📝 Minor Notes

1. PR description typo - The description says the recessed dark token changes from oklch(15% 0 0) → oklch(12% 0 0), but the actual change goes the opposite direction (12% → 15%). The code is correct - just the description has the direction reversed.

2. Unmentioned fix - There's also a fix to kumo-fill-hover dark mode in theme-kumo.css (changed from --color-neutral-700 to --color-neutral-800) that wasn't mentioned in the changeset.

The review has been submitted as a comment review on the PR.

github run

[github-actions]

Docs Preview

View docs preview

Commit: 4f7ed26

[github-actions]

Visual Regression Report

5 screenshot(s) with visual changes:

Button / Loading State

2 px (0%) changed

Before	After	Diff

Dialog / Dialog With Select

236 px (0.23%) changed

Before	After	Diff

Dialog / Dialog With Dropdown

130 px (0.13%) changed

Before	After	Diff

Select / Select Loading

0 px (0%) changed

Before	After	Diff

Select (Open)

200 px (0%) changed

Before	After	Diff

26 screenshot(s) unchanged

• Button / Basic
• Button / Variant: Primary
• Button / Variant: Secondary
• Button / Variant: Ghost
• Button / Variant: Destructive
• Button / Variant: Outline
• Button / Variant: Secondary Destructive
• Button / Sizes
• Button / With Icon
• Button / Icon Only
• Button / Disabled State
• Button / Title
• Dialog / Dialog With Actions
• Dialog / Dialog Basic
• Dialog / Dialog Alert
• Dialog / Dialog Confirmation
• Dialog / Dialog With Combobox
• Dialog (Open)
• Select / Select Basic
• Select / Select Without Label
• Select / Select With Field
• Select / Select Placeholder
• Select / Select With Tooltip
• Select / Select Custom Rendering
• Select / Select Multiple
• Select / Select Complex

---

Generated by Kumo Visual Regression

[geoquant]

/bonk review again

[ask-bonk]

Review Summary

This PR successfully addresses the two stated goals:

1. Token Rename: kumo-ring → kumo-hairline

The rename is comprehensive and consistently applied across all 34 changed files:

• 12 component files - button, checkbox, input, input-group, radio, select, sensitive-input, sidebar, table, tabs, toast
• 2 theme CSS files - theme-kumo.css, theme-fedramp.css
• Theme generator config - config.ts updated with the new token name
• Figma integration - generators and parsers updated
• Component registry metadata - metadata.ts styling states updated
• Lint rules - both root and package-level no-primitive-colors.js
• Documentation - USAGE.md, colors.mdx, AGENTS.md files
• Tests - flow.test.tsx and tailwind-to-figma.test.ts

This resolves the naming conflict with Tailwind's built-in ring utility.

2. Documentation Alignment

The USAGE.md and colors.mdx now share consistent:

• Token categorization (Surface Hierarchy, Brand, Semantic Status Colors, Text Colors, Borders & Rings)
• Token descriptions
• Structure and organization

3. Additional Fixes (Correctly Documented in Changeset)

• Recessed dark token fix: Corrected from oklch(12% 0 0) to oklch(15% 0 0) in config.ts and regenerated in theme-kumo.css
• Fill-hover dark token fix: Changed from --color-neutral-700 to --color-neutral-800 for consistency

Visual Regression Results

The 8 screenshots with minor pixel changes are expected - they reflect the token rename but no actual visual differences should be perceptible since the color values remain unchanged.

Changeset Accuracy

The changeset correctly identifies this as a patch change and accurately describes all modifications.

---

Overall: Well-executed cleanup PR that improves consistency and avoids naming conflicts. All changes are properly documented and consistently applied. Approved!

[ask-bonk]

Review Complete ✅

I've submitted my approval for PR #355. Here's a summary of my review:

Key Findings

1. Token Rename (kumo-ring → kumo-hairline)

• Comprehensive rename across all 34 files
• Correctly applied in 12 component files, 2 theme CSS files, Figma generators, lint rules, documentation, and tests
• Resolves the Tailwind naming conflict effectively

2. Documentation Alignment

• USAGE.md and colors.mdx now share consistent token categorization and descriptions
• Clear documentation of the distinction between kumo-hairline (flat surfaces) and kumo-line (elevated surfaces)

3. Additional Fixes

• Recessed dark token: Fixed from oklch(12% 0 0) to oklch(15% 0 0) in config.ts and regenerated CSS
• Fill-hover dark token: Changed from neutral-700 to neutral-800 for consistency

4. Changeset Accuracy

• Correctly identifies patch changes for both packages
• Accurately describes all modifications

Visual Regression

The 8 screenshots with minor pixel changes are expected - they reflect the token rename but no actual visual differences since color values remain unchanged.

Overall: A well-executed cleanup PR that improves consistency, resolves naming conflicts, and establishes a single source of truth for token documentation. All changes are properly documented and consistently applied.

github run