docs: epic/v3 work plan

docs/v3-plan.md

@@ -0,0 +1,265 @@
+# Core-Styles v3 — Work Plan
+
+## Branch / PR Map
+
+```
+main ◄── epic/v3                          PR #454  (Step 3 — last to merge)
+              ▲
+              ├── epic/v3--reorg           PR #455  (Step 1)
+              └── epic/v3--gh-345-…figma  PR #456  (Step 2)
+```
+
+| PR | Title | Branch → Base | Link |
+|----|-------|---------------|------|
+| #454 | refactor: v3 | `epic/v3` → `main` | https://github.com/TACC/Core-Styles/pull/454 |
+| #455 | refactor(v3): reorganize styles per client library | `epic/v3--reorg` → `epic/v3` | https://github.com/TACC/Core-Styles/pull/455 |
+| #456 | feat(v3): use re-brand colors from figma | `epic/v3--gh-345-tokens-from-figma` → `epic/v3` | https://github.com/TACC/Core-Styles/pull/456 |
+
+---
+
+## Execution Order
+
+Steps 1 and 2 touch different files and can run in parallel.
+Step 3 must come last.
+
+---
+
+## PR #455 — Reorganize Styles per Client Library
+
+**Branch:** `epic/v3--reorg`  **Base:** `epic/v3`
+
+### What it does
+
+Moves every pattern into a per-library subdirectory that mirrors the client
+library's own organization. Each pattern gets its own named folder containing
+its source, template, config, and demo styles — co-located.
+
+**Reference: a finished item** (`tacc/components/c-button/`):
+
+```
+tacc/components/c-button/
+  c-button.postcss         ← source (moved inside the subdir, not flat)
+  c-button--cms.postcss    ← variant source (also inside subdir)
+  c-button.hbs             ← Fractal template
+  c-button.selectors.postcss
+  config.yml               ← includes context.subdir (see Step B below)
+  demo.css                 ← demo-context styles
+```
+
+### Done ✅
+
+| Category | Status |
+|----------|--------|
+| Bootstrap 3 | ✅ fully reorganized |
+| Bootstrap 4 | ✅ fully reorganized |
+| Bootstrap 5 | ✅ fully reorganized |
+| Django CMS variants (`djangocms-*`) | ✅ moved to own dirs |
+| Docs libs (`mkdocs`, `pymdownx`, `python-markdown`, `readthedocs`, `tacc-docs`) | ✅ moved |
+| TACC / `components/` | ✅ fully reorganized |
+
+### Remaining ❌
+
+#### 1. TACC sub-libraries — per-item reorganization
+
+Six sub-libraries still need each of their patterns to be reorganized.
+Apply the same 3-step pattern used for `tacc/components/` to each item in:
+
+| Sub-library | Path |
+|-------------|------|
+| elements | `src/lib/_imports/tacc/elements/` |
+| generics | `src/lib/_imports/tacc/generics/` |
+| objects | `src/lib/_imports/tacc/objects/` |
+| settings | `src/lib/_imports/tacc/settings/` |
+| tools | `src/lib/_imports/tacc/tools/` |
+| trumps | `src/lib/_imports/tacc/trumps/` |
+
+**The 3-step pattern per item** (where `{lib}` = e.g. `elements`, `{item}` = e.g. `links`):
+
+**Step A — Move source into subdir**
+```
+tacc/{lib}/{item}.postcss         → tacc/{lib}/{item}/{item}.postcss
+tacc/{lib}/{item}--variant.postcss → tacc/{lib}/{item}/{item}--variant.postcss
+tacc/{lib}/{item}.selectors.postcss → tacc/{lib}/{item}/{item}.selectors.postcss
+```
+(All `.postcss` files that belong to this item move together.)
+
+**Step B — Add `context.subdir` to the item's `config.yml`**
+```yaml
+context:
+  subdir: "tacc/{lib}/{item}"
+```
+If the item does not yet have a `config.yml`, create one with at minimum:
+```yaml
+context:
+  subdir: "tacc/{lib}/{item}"
+```
+
+**Step C — Remove the `(CMS|…)` prefix from the Fractal label**
+
+In `config.yml` or variant `label:` fields:
+```yaml
+# Before:
+label: (CMS) Links
+# After:
+label: Links
+```
+
+> **Note:** Some patterns have multiple `.postcss` files (e.g. `root.postcss`,
+> `root--cms.postcss`, `root--portal.postcss`). All variants belong inside the
+> same subdir alongside the main file. The subdir name should be the
+> "base name" without the variant suffix (e.g. `root/`).
+
+> **Note:** Some patterns are partially reorganized — a subdirectory already
+> exists with some files (`config.yml`, `.hbs`, `readme.md`) but the source
+> `.postcss` is still flat at the parent level. Treat these the same way:
+> move the flat `.postcss` (and any variants) into the existing subdir and
+> complete Steps B and C as normal.
+
+> **Note:** Some items (e.g. `_elements.config.yml`, `demo.postcss`,
+> `README.css`, `selectors.*.postcss`) are infrastructure files, not patterns.
+> Do not create subdirs for them.
+
+#### 2. Quality-of-life — absolute imports
+
+- **Support absolute imports:** Update the PostCSS config / build tooling so
+  `@import` paths can be written relative to `src/lib/_imports/` (or repo root)
+  rather than relative to the current file.
+- **Use absolute imports:** Once supported, rewrite all relative `@import`
+  paths across all `.postcss` source files to use absolute paths.
+
+  This makes future reorganization much safer (no broken relative paths).
+
+#### 3. UX — Fractal sidebar grouping
+
+Group related libraries in the Fractal demo sidebar:
+
+| Current labels | Target group label |
+|----------------|-------------------|
+| Bootstrap 3, Bootstrap 4, Bootstrap 5 | **Bootstrap** |
+| Django CMS Blog, Django CMS Forms, Django CMS Picture | **Django CMS** |
+| MkDocs, PyMdown, Python-Markdown, ReadTheDocs, TACC Docs | **Styles for Docs** |
+
+This is configured in `fractality.config.js` and/or the relevant `config.yml`
+files.
+
+### Testing
+
+1. `npm start` — launch the Fractal dev server
+2. Open every pattern in the sidebar — confirm all render correctly
+3. Verify sidebar organization mirrors the client library's own docs:
+   - [Bootstrap 3](https://getbootstrap.com/docs/3.4/)
+   - [Bootstrap 4](https://getbootstrap.com/docs/4.6/)
+   - [Bootstrap 5](https://getbootstrap.com/docs/5.3/)
+   - [TACC v2 reference](https://github.com/TACC/Core-Styles/tree/v2.39.0/src/lib/_imports)
+4. No regressions — styles should look identical to before the reorg
+
+---
+
+## PR #456 — Use Re-brand Colors from Figma
+
+**Branch:** `epic/v3--gh-345-tokens-from-figma`  **Base:** `epic/v3`  
+**Label:** paused  **Completes:** [issue #457](https://github.com/TACC/Core-Styles/issues/457)
+
+### What it does
+
+Adds CSS custom-property design tokens from TACC's Figma re-brand. All token
+files live under `src/v3/variables/`.
+
+**New files:**
+```
+src/v3/variables/tokens/
+  primitives-designsafe.css    ← concrete color values for DesignSafe
+  primitives-tacc-cms.css      ← concrete color values for TACC CMS
+  primitives-tacc-portal.css   ← concrete color values for TACC Portal
+  tokens-dark.css              ← semantic aliases (dark theme)
+  tokens-light.css             ← semantic aliases (light theme)
+src/v3/variables/
+  designsafe.dark.css / designsafe.light.css
+  tacc-cms.dark.css / tacc-cms.light.css
+  tacc-portal.dark.css / tacc-portal.light.css
+```
+
+**Token structure (two layers):**
+- **Primitives** — concrete values per product  
+  e.g. `--color-traffic-red-normal: #e03535`
+- **Semantics** — intent-to-primitive aliases  
+  e.g. `--color-danger-normal: var(--color-traffic-red-normal)`
+
+### Remaining ❌
+
+> **Blocker — human required:** Task 1 below requires access to Figma and
+> cannot be completed autonomously. All other tasks can proceed independently,
+> but the PR should not be marked ready for review until task 1 is resolved.
+
+1. **Confirm token values** _(human required — needs Figma access)_ — verify
+   the manually-entered values in `src/v3/variables/tokens/primitives-*.css`
+   are current against the latest TACC re-brand spec in Figma.
+2. **Verify build integration** — confirm the token files are imported by the
+   main build entry points in `epic/v3` (they currently live under `src/v3/`,
+   which may or may not be included in the main build yet).
+3. **Fill in the Testing section** of the PR description (currently `1. …`).
+4. **Remove the `paused` label** and mark as ready for review.
+
+### Testing
+
+- Build the full stylesheet (`npm run build`) and confirm no errors.
+- Open a pattern in Fractal that uses a semantic color variable (e.g. a danger
+  state) and confirm the re-brand color is applied.
+
+---
+
+## PR #454 — Refactor: v3 (Epic / Umbrella)
+
+**Branch:** `epic/v3`  **Base:** `main`
+
+### What it does
+
+This is the base branch all other v3 work merges into. Key changes already in place:
+
+| Change | Detail |
+|--------|--------|
+| `.css` → `.postcss` | All source files renamed; built `.css` output is never confused with source |
+| No committed `/dist` | Build output is generated-only; never committed |
+| `bin/build-each.js` | Builds individual stylesheets in place |
+| `bin/only-commit-source.js` | Lint guard: errors if compiled `.css` is found inside `src/` — fixed and passing as of PR #604 |
+| `3.0.0-alpha.0` | Version bump |
+
+**Backwards-compatibility:**
+- Styles: ✅ backwards-compatible
+- Directory structure of `/dist`: ❌ breaking change
+- Source file extensions (`.postcss`): ❌ breaking change
+
+### Remaining ❌
+
+1. **Wait for #455 and #456** to be merged into `epic/v3`.
+2. **Sync** `epic/v3` with `main` one final time before merging.
+3. **Fill in** the PR description's `Changes`, `Testing`, and `UI` sections.
+4. **Verify full build** passes: `npm run build && npm run lint`.
+5. **Remove draft status** and request review.
+
+### Testing
+
+```sh
+npm run lint       # must pass (no compiled .css in src/)
+npm run build      # must complete without errors
+npm start          # demo server must start and show all patterns
+```
+
+---
+
+## Notes
+
+### The `only-commit-source.js` guard
+
+Runs as `prepublishOnly` and via `npm run lint`. Passes on `epic/v3` and
+`epic/v3--reorg` as of PR #604. After any merge from `main`, run
+`npm run lint` — new `.css` source files from `main` may need renaming to
+`.postcss`.
+
+### Ghost directories on `epic/v3--reorg`
+
+`src/lib/_imports/objects/o-offset-content/` has a `config.yml`, `.hbs`, and
+`readme.md` (added by a recent main merge) but no `.postcss` source. The
+source lives at `tacc/objects/o-offset-content.postcss`. This directory is a
+leftover from the pre-reorg state and should be cleaned up as part of the
+objects reorganization in PR #455.

src/lib/_imports/bootstrap4/components/btn/btn.hbs

@@ -9,18 +9,18 @@
         class="btn btn-{{type}}{{#if size}} btn-{{size}}{{/if}}{{#if active}} active{{/if}}"
         {{#if disabled}}disabled{{/if}}
     >
-        {{#if hasIconBefore}}<i class="icon icon-user"></i>{{/if}}
+        {{#if hasIconBefore}}<i class="icon icon-user">Meaningful text or add [aria-hidden="true"]</i>{{/if}}
         {{text}}
-        {{#if hasIconAfter}}<i class="icon icon-user"></i>{{/if}}
+        {{#if hasIconAfter}}<i class="icon icon-user">Meaningful text or add [aria-hidden="true"]</i>{{/if}}
     </button>
     {{else}}
     <a
         href="{{href}}"
         class="btn btn-link"
     >
-        {{#if hasIconBefore}}<i class="icon icon-user"></i>{{/if}}
+        {{#if hasIconBefore}}<i class="icon icon-user">Meaningful text or add [aria-hidden="true"]</i>{{/if}}
         {{text}}
-        {{#if hasIconAfter}}<i class="icon icon-user"></i>{{/if}}
+        {{#if hasIconAfter}}<i class="icon icon-user">Meaningful text or add [aria-hidden="true"]</i>{{/if}}
     </a>
     {{/unless}}
     </dd>

src/lib/_imports/bootstrap4/utilities/color-text.css

@@ -43,7 +43,7 @@ a.text-primary:is(
   :hover,
   :focus
 ) {
-  color: var(--global-color-accent--normal) !important;
+  color: var(--global-color-accent--light) !important;
 }
 a.text-secondary:is(
   :link,
@@ -62,5 +62,5 @@ a[class*="text-"]:not(
   :hover,
   :focus
 ) {
-  color: var(--global-color-accent--normal) !important;
+  color: var(--global-color-accent--light) !important;
 }

src/lib/_imports/bootstrap4/utilities/color-text/color-text.hbs

@@ -7,9 +7,9 @@
         class="text-{{type}}{{#if size}} text-{{size}}{{/if}}"
         {{#if disabled}}disabled{{/if}}
     >
-        {{#if hasIconBefore}}<i class="icon icon-user"></i>{{/if}}
+        {{#if hasIconBefore}}<i class="icon icon-user">Meaningful text or add [aria-hidden="true"]</i>{{/if}}
         {{text}}
-        {{#if hasIconAfter}}<i class="icon icon-user"></i>{{/if}}
+        {{#if hasIconAfter}}<i class="icon icon-user">Meaningful text or add [aria-hidden="true"]</i>{{/if}}
     </{{#if asLink}}a{{else}}p{{/if}}>
     </dd>
     {{/types}}

src/lib/_imports/components/bootstrap.modal.postcss

@@ -42,7 +42,6 @@
 
 /* To darken close button */
 .modal-header .close {
-  color: var(--global-color-primary--x-dark);
   opacity: 1;
 }
 /* FAQ: The specificity matches Bootstrap */

src/lib/_imports/components/c-app-card/c-app-card.hbs

@@ -8,7 +8,7 @@
     <div class="c-app-card">
     {{/if}}
       <h3 class="c-app-card__title">
-        {{#if icon}}<i class="icon icon-user"></i>{{/if}}
+        {{#if icon}}<i class="icon icon-user">Meaningful text or add [aria-hidden="true"]</i>{{/if}}
         {{!-- FAQ: These custom icons are not available in Cortal --}}
         {{!-- {{#if icon}}<i class="icon icon-{{icon}}"></i>{{/if}} --}}
         {{title}}

src/lib/_imports/components/c-feed-list/c-feed-list.hbs

@@ -13,7 +13,7 @@
             <h3>Upcoming Events</h3>
 
             <article>
-                <time>May 15, 2024</time>
+                <time datetime="2024-05-15">May 15, 2024</time>
                 <h4>
                     <a href="#">Workshop: Advanced Data Analysis</a>
                 </h4>
@@ -43,18 +43,31 @@
             <h3>User Updates</h3>
 
             <article>
-                <time data-prefix="Published:" datetime="2024-04-29">
-                    <span>April 29, 2024</span>
+                <time
+                    data-prefix="Published:"
+                    aria-label="Published April 29, 2024"
+                    datetime="2024-04-29"
+                >
+                    April 29, 2024
                 </time>
                 <h4><a href="#" target="_blank">New Feature Release</a></h4>
                 <p>We're excited to announce the release of new features to enhance your experience. These updates include improved performance and additional customization options.</p>
                 <p><a href="#" class="c-button c-button--primary" target="_blank">Learn More</a></p>
             </article>
 
             <article class="has-update">
-                <time data-prefix="Published:" datetime="2024-04-28">
-                    <span>April 28, 2024</span>
-                    <span class="c-pill c-pill--is-updated">Update</span>
+                <time
+                    data-prefix="Published:"
+                    aria-label="Published April 28, 2024"
+                    datetime="2024-04-28"
+                >
+                    April 28, 2024
+
+                    <span
+                        class="c-pill c-pill--is-updated"
+                    >
+                        Updated
+                    </span>
                 </time>
                 <h4><a href="#" target="_blank">System Maintenance</a></h4>
                 <p>Planned maintenance will occur this weekend. The system will be unavailable from 10 PM to 2 AM.</p>

src/lib/_imports/components/c-update/c-update.hbs

@@ -4,7 +4,11 @@
     <aside class="c-update">
       <header class="c-update__header">
         <h3 class="c-update__title">
-          <span class="c-pill c-pill--is-updated">Update</span>&nbsp;
+          <span
+            class="c-pill c-pill--is-updated"
+          >
+            Updated
+          </span>&nbsp;
         </h3>
         <span>Published:</span>&nbsp;
         <time datetime="2023-10-13T14:27:18.637000">