docs: epic/v3 work plan

[wesleyboar]

Warning

Qodo review might have something useful to share. Merge chaos and large context window and plain ol' A.I. mistakes could have lead to inaccuracies that Qodo, independent review, may have caught.

Overview

Document what is left to do on PRs #454, #455, #456.

Related

documents:

• refactor: v3 #454
• refactor(v3): reorganize styles per client library #455
• feat(v3): use re-brand colors from figma #456

Changes

• adds document

Testing

1. N/A

UI

Read https://github.com/wesleyboar/Core-Styles/blob/005ccef1/docs/v3-plan.md.

[qodo-code-review]

ⓘ You are approaching your monthly quota for Qodo. Upgrade your plan

Review Summary by Qodo

Document Core-Styles v3 refactoring work plan and execution strategy

📝 Documentation

Walkthroughs

Description

• Documents v3 refactoring work plan across three related PRs
• Maps branch structure and execution order for v3 migration
• Details PR #455: reorganize styles per client library structure
• Details PR #456: integrate Figma re-brand color tokens
• Details PR #454: v3 epic umbrella with build infrastructure changes

Diagram

flowchart LR
  main["main"]
  epic["epic/v3<br/>PR #454"]
  reorg["epic/v3--reorg<br/>PR #455"]
  tokens["epic/v3--gh-345-tokens-from-figma<br/>PR #456"]
  
  reorg -- "merge second" --> epic
  tokens -- "merge third" --> epic
  epic -- "merge last" --> main
  
  style epic fill:#e1f5ff
  style reorg fill:#fff3e0
  style tokens fill:#f3e5f5
  style main fill:#e8f5e9

Loading

File Changes

1. docs/v3-plan.md 📝 Documentation +282/-0

Add comprehensive v3 refactoring work plan documentation

• Creates comprehensive v3 work plan document with branch/PR mapping
• Documents execution order: PR #455 → PR #456 → PR #454
• Details PR #455 reorganization tasks: TACC sub-libraries, absolute imports, Fractal grouping
• Details PR #456 token integration: primitives and semantic color variables
• Details PR #454 epic changes: .css to .postcss conversion, build infrastructure
• Includes testing procedures and remaining tasks for each PR
• Explains .css vs .postcss distinction and ghost directory cleanup

docs/v3-plan.md

---

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (2) 📘 Rule violations (0) 📎 Requirement gaps (0)

1. Wrong CSS depth rule 🐞 Bug ✓ Correctness

Description

docs/v3-plan.md says only-commit-source.js allows .css files “3+ levels deep” under _imports, but
the implementation only ignores a very specific path shape (_imports/<dir1>/<dir2>/<file>.css).
Following the doc literally can lead to lint/publish failures when a .css file is placed deeper than
that allowed shape.

Code

docs/v3-plan.md[R267-271]

+- The `only-commit-source.js` guard allows `.css` files that are **3+ levels**
+  deep inside `_imports/` (e.g. `bootstrap5/utilities/link.css`) — these are
+  treated as built-in-place outputs
+- A `.css` file at a shallower depth (e.g. `tools/x-pill.css`) will trip the
+  guard and must be renamed to `.postcss`

Evidence

The doc claims “3+ levels” are allowed, implying deeper nesting is OK; however the lint guard
ignores only paths matching exactly two directories under _imports (three path segments total), so
deeper .css files will be reported as built artifacts in src/ and cause the lint script to exit(1).

docs/v3-plan.md[267-271]
bin/only-commit-source.js[20-26]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The work plan documents the `.css` exception for `bin/only-commit-source.js` as allowing `.css` files that are **"3+ levels deep"** under `_imports/`, but the actual ignore rule only matches `_imports/<dir1>/<dir2>/<file>.css` (exactly 3 path segments after `_imports/`). This mismatch can cause developers to place generated `.css` files in deeper locations that will fail `npm run lint` / `prepublishOnly`.

### Issue Context
- The documentation is intended to guide v3 work; it should not misstate CI-enforced rules.

### Fix Focus Areas
- docs/v3-plan.md[267-271]
- bin/only-commit-source.js[20-26]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Ambiguous merge-order labels 🐞 Bug ✧ Quality

Description

The branch diagram labels PR #455/#456 as “merge second/merge third” while the document’s Execution
Order describes them as Step 1/Step 2, making the diagram’s numbering ambiguous. This can confuse
coordination on which PR should be merged when.

Code

docs/v3-plan.md[R6-10]

+main ◄── epic/v3                          PR #454  (last to merge)
+              ▲
+              ├── epic/v3--reorg           PR #455  (merge second)
+              └── epic/v3--gh-345-…figma  PR #456  (merge third)
+```

Evidence

The diagram uses ordinal merge labels (“second/third”) but the later Execution Order defines the
actual step sequence. Without an explicit statement of what the ordinals are relative to (e.g.,
‘overall sequence into main’ vs ‘sequence into epic/v3’), the diagram can be read as contradicting
the steps.

docs/v3-plan.md[6-10]
docs/v3-plan.md[23-31]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The Branch / PR Map uses ordinal wording (“merge second/merge third”) that is ambiguous next to the explicit Step 1/2/3 execution order. This ambiguity can confuse readers about the intended sequencing.

### Issue Context
Keep the diagram but align its wording with the Execution Order section, or explicitly define what the ordinals refer to.

### Fix Focus Areas
- docs/v3-plan.md[6-10]
- docs/v3-plan.md[20-35]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

ⓘ The new review experience is currently in Beta. Learn more