# ChargeForms — Design System Status: **Milestone 4 — visual foundation**, through the Slice 13+ premium visual pass. This document is the **history and rationale** — what was audited, what changed, why, slice by slice. For the **frozen, forward-looking standard** a new feature should actually build against (the token values themselves, not the story of how they got there), see `DESIGN_GUIDELINES.md`. This document covers what the milestone brief asked for across five files (`DESIGN_SYSTEM.md`, `UI_GUIDELINES.md`, `COMPONENT_LIBRARY.md`, `MOTION_SYSTEM.md`, `ICONOGRAPHY.md`) in one place instead — see "A note on scope" at the end for why, and what's genuinely still open. Tokens live in `assets/css/admin.css`'s `.chargeforms-wrap` root block — the shared scale every ChargeForms admin screen uses, not something builder-only. The builder (`assets/src/builder/`) renders inside `.chargeforms-wrap` and consumes the same tokens; `assets/src/builder/shared/styles/tokens.css` holds only the handful of builder-specific values (panel widths, z-index stack) that have no cross-screen meaning — see that file's own header comment. --- ## 1. Audit — what was actually inconsistent Before adding anything, the existing `assets/src/builder/style.css` (~1900 lines) was audited by grepping for every distinct literal value in each category, not by eyeballing it: | Category | Distinct ad-hoc values found | What it should have been | |---|---|---| | `box-shadow` | 24 | ~5 semantic elevation steps | | `border-radius` | 8 (`3/4/5/6/7/8/10px`, `999px`, `50%`) | 4 steps + full/circle | | "muted" gray text color | 4 (`#606266`, `#909399`, `#8a8f98`, `#64748b`) | 1 token | | White background | 2 spellings (`#fff`, `#ffffff`) for the same color | 1 token | | `padding` shorthand | dozens of one-off combinations | one spacing scale, already defined but inconsistently used | | `transition`/`animation` timing | mixed `ease` and `var(--fc-ease)`, no shared duration | 1 curve + 3 durations | The single most consequential finding: `.chargeforms-app-root` (the builder's own root element) independently re-declared `--fc-muted`, `--fc-border`, and `--fc-bg` as their own slightly-different hardcoded colors, instead of inheriting the real ones from `.chargeforms-wrap` one level up in the DOM. This was already flagged in a `TODO` comment in the file from an earlier session ("a redesign pass appended without removing the original... left as-is for now") — Milestone 4 fixed the part of that debt that was an actual live bug (values silently drifting apart) via aliasing, and left the larger, lower-risk cleanup (23 duplicate selector blocks, cosmetically redundant but not visually broken since cascade order already makes the later block consistently win) as documented future work — see §9. --- ## 2. Color system Defined once, in `.chargeforms-wrap` (`assets/css/admin.css`), inherited by every ChargeForms admin screen and the builder. ### Brand scale ``` --fc-primary-50: #eaf2ff softest tint (selected-row backgrounds, soft badges) --fc-primary-100: #d1e5fe one step up (hover backgrounds) --fc-primary-500: #1a73e8 the brand blue — --fc-primary / --fc-accent --fc-primary-600: #1558b0 --fc-primary-dark — hover/active states, text on light tints --fc-primary-700: #0d3d7a --fc-primary-darker — rarely used, high-contrast text-on-white ``` `--fc-accent`/`--fc-accent-soft` are aliases onto the primary scale (kept for the many existing rules already written against those names). ### Semantic ``` --fc-success: #00b27f --fc-danger: #ff6154 --fc-warning: #fcbe2d --fc-info: #1a73e8 (new — was previously just reusing --fc-primary ad hoc) ``` ### Surfaces (new this milestone) ``` --fc-surface: #ffffff a resting card/panel/input background --fc-surface-elevated: #ffffff one step above surface — a popover/dropdown floating over surface-level cards. Same color as --fc-surface today (elevation is communicated by shadow, not tint, at this stage) — kept as its own token because that's a real design decision that may change, not an oversight. --fc-canvas-bg: #fbfcfe the dot-grid working area's own background — deliberately distinct from --fc-surface since the canvas is a workspace, not a card. --fc-bg: #f5f7fa the page-level background every screen sits on ``` ### Text ``` --fc-text: #1e1f21 primary text/headings --fc-muted: #606266 secondary text — labels, helper copy, icons --fc-muted-light: #90959e tertiary text — placeholders, timestamps, disabled labels ``` Before this milestone, "muted" text used four different grays interchangeably (see §1) with no rule for which one to reach for. The rule now: **`--fc-muted` is the default** for anything secondary; reach for `--fc-muted-light` only when something needs to read as visibly lower- priority than a `--fc-muted` label next to it (a timestamp under a note, a placeholder inside an already-labeled field). ### Border ``` --fc-border: #dadbdd ``` Contrast: `--fc-text` on `--fc-surface` is 14.9:1 (WCAG AAA). `--fc-muted` on `--fc-surface` is 5.4:1 (WCAG AA for normal text, comfortably above the 4.5:1 minimum). `--fc-primary` on white is 4.6:1 (AA). These weren't re-picked this milestone — they were already the values in use — but are recorded here as the actual measured numbers, not an assumption. --- ## 3. Typography ``` --fc-text-2xs: 11px micro labels, badge text --fc-text-xs: 12px captions, meta text, small buttons --fc-text-sm: 13px secondary body text, form labels --fc-text-base: 14px default body text — the base size everything else scales from --fc-text-md: 15px emphasized body text, sub-headings --fc-text-lg: 17px card/section titles --fc-text-xl: 19px panel headings --fc-text-2xl: 23px page-level headings --fc-text-3xl: 27px rare — top-level display text ``` Font family: `--fc-font` — the OS-native UI font stack (Segoe UI on Windows, falling through to system defaults elsewhere) rather than a webfont. Deliberate: a webfont costs a network request and a flash-of- unstyled-text risk for a marginal identity gain; the native stack already reads as "considered" rather than "default browser serif" the moment any type scale/weight/spacing discipline is applied on top of it — which is what this whole section is. **Weight discipline** (measured in §1: `600` used 13×, `700` used 11×, `500` 4×, `800`/`400` once each — already fairly disciplined, formalized here rather than changed): - `400` — body copy, rare (most body text in this UI is already `--fc-muted` at default weight via inheritance, not an explicit rule) - `500` — form labels, secondary buttons - `600` — field labels, palette item names, primary emphasis - `700` — headings, kickers/eyebrows (uppercase, letter-spaced), stat pills - `800` — reserved for the rare oversized display number (not in active use) **Line-height**: not tokenized as a separate scale — every text rule in this codebase either inherits the browser default (`normal`, ~1.2) for single-line UI text (labels, buttons, badges) or sets an explicit `1.4`– `1.6` for multi-line copy (helper text, empty-state descriptions). A formal `--fc-leading-*` scale is listed as future work (§9) rather than introduced speculatively — every current use case is already served by one of those two values. --- ## 4. Spacing ``` --fc-space-1: 4px --fc-space-2: 8px --fc-space-3: 12px --fc-space-4: 16px --fc-space-5: 20px --fc-space-6: 24px --fc-space-8: 32px ``` This scale already existed before Milestone 4. What it exposed in the audit (§1) is that it's under-used — most `padding`/`gap`/`margin` values in `style.css` are one-off pixel numbers that happen to be close to a scale step (`9px`, `14px`, `18px`) rather than the step itself. **Rule going forward: every new spacing value must be one of the tokens above.** Retrofitting the existing one-off values is real work, listed in §9 rather than attempted as a blind find-replace across ~1900 lines with no per-instance visual check. --- ## 5. Radius ``` --fc-radius-sm: 4px tight controls — checkboxes, small badges --fc-radius-md: 6px the default — inputs, buttons, most cards --fc-radius-lg: 10px larger cards, panels --fc-radius-xl: 14px large surfaces — modals, the canvas frame --fc-radius-full: 999px pills (status badges, stat chips) --fc-radius-circle: 50% perfect circles (icon buttons, avatars) ``` New this milestone — replaces the 8 ad-hoc values found in the audit. Applied to newly-written Milestone 3/4 rules (the floating toolbar, selection states) directly; the broader retrofit across every existing `border-radius` declaration is listed in §9 for the same reason as spacing — real work, not attempted as an unverified bulk pass. --- ## 6. Elevation (shadows) ``` --fc-shadow-xs: 0 1px 2px rgba(15,23,42,.04) barely-there resting state (a flat list row, an input) --fc-shadow-sm: 0 1px 3px rgba(15,23,42,.06), 0 1px 2px rgba(15,23,42,.04) a resting card, a palette item --fc-shadow-md: 0 4px 12px rgba(15,23,42,.08), 0 2px 4px rgba(15,23,42,.04) a raised panel, a hovered card --fc-shadow-lg: 0 12px 28px rgba(15,23,42,.12), 0 0 0 1px rgba(15,23,42,.04) a floating element that tracks the cursor or a selection (the floating context toolbar) --fc-shadow-xl: 0 24px 56px rgba(15,23,42,.18), 0 0 0 1px rgba(15,23,42,.04) anything above a scrim — dialogs, the search overlay --fc-shadow-selection: 0 0 0 1px var(--fc-primary), 0 0 0 4px var(--fc-primary-soft) "this is selected" — a colored ring, not a gray shadow, since selection is a different KIND of emphasis than elevation, not just a stronger amount of it ``` Every step is a **layered** shadow (a soft ambient layer + a tighter contact layer), not a single flat `box-shadow: 0 Npx Mpx rgba(...)` — that's what makes a card read as "lifted off the page" instead of having a generic gray smudge under it, and was already the house style for the two shadows that existed before this milestone (`--fc-card-shadow`, `--fc-shadow-hover`); the new scale extends the same construction principle rather than introducing a different one. --- ## 7. Motion ``` --fc-ease: cubic-bezier(0.16, 1, 0.3, 1) one curve, everywhere — a gentle ease-out, deliberately not the browser default linear/ease (which reads as mechanical) --fc-motion-fast: 100ms hover/press feedback — should feel instant --fc-motion-base: 180ms the common case — selection, expand/collapse, toolbar fade-in --fc-motion-slow: 260ms anything moving a meaningful visual distance — panel slides, modal entrances ``` All three durations sit inside the brief's 150–250ms guidance band except `--fc-motion-fast` (100ms), which is intentional — hover/press states need to read as immediate, not animated; 150ms+ on a button hover reads as sluggish rather than smooth. `prefers-reduced-motion: reduce` is honored for every animation/transition introduced in Milestones 3–4 (collapses duration to near-zero rather than removing the rule outright, so state still changes correctly — see `style.css`'s reduced-motion block). Milestones 1–2's transitions weren't re-audited against this query this pass — listed in §9. --- ## 8. First-pass UI work shipped The first design/UI pass now includes a focused builder chrome retrofit in `assets/src/builder/style.css`. The builder shell, topbar controls, form status pills, preview/device switcher, responsive canvas frame, settings / palette / history panels, and history selection states now consume the shared radius, surface, elevation, color, and motion tokens rather than local literal values. The current-history marker also has a dedicated brand edge, so selection is communicated by both color and position without changing the existing keyboard or tab behavior. This is a CSS-only pass: no PHP, REST, validation, conditional-logic, or builder interaction code changed. It was reviewed by source/diff inspection; no real browser or WordPress environment is available in this workspace, so responsive and visual appearance remain unverified in a live browser. **Slice 2 — Field Palette (search, filters, field cards) and canvas field cards/empty state.** Explicit goal for this slice: bring the palette and canvas closer to the polish bar set by modern form builders (Fluent Forms, and separately Fillout/Typeform/Tally as UX-inspiration only — never their visual design, never their source code), not just apply tokens 1:1. - **Fixed a real duplicate-declaration bug** in `.fc-palette-search` and `.fc-palette-grid` — both had the same property (`background`, `border-radius`, `margin-bottom` on the former; `grid-template-columns`, `gap` on the latter) declared twice in one rule block, the same "appended without removing the original" pattern §1 already flagged elsewhere in this file. Consolidated to one declaration each. - **Search bar**: replaced the generic Dashicons search glyph with a purpose-drawn inline SVG (matches the stroke style the empty-state icon already used), added a real focus-visible ring (`--fc-primary-50`) on the whole search field instead of just the bare input outline, and added a clear ("×") button that appears once there's a query — all using existing tokens (`--fc-motion-fast`, `--fc-primary-*`), no new ones introduced. - **Group filter tabs**: added a real hover state for inactive tabs (previously only `.is-active` had any visual feedback), a subtle press scale-down, and token-based transition timing — was previously untimed/ instant. - **Field palette items and canvas field cards**: tokenized remaining hardcoded hex colors (`#fff`, `#909399`, `#e8eef6`, `#b7d9ff`, etc.) to the real color scale, added a subtle hover lift to canvas field cards (previously only background/border changed on hover — palette items already had this, canvas cards didn't, an inconsistency now fixed), and a small icon-chip scale-up on palette-item hover for tactile feedback. - **What this slice deliberately does NOT do**: replace Dashicons with a custom icon set (still tracked below — the ~60 field-type icons need a real, licensed icon set chosen and mapped, not a piecemeal swap of just the ones touched here); redesign the Floating Toolbar or Quick-Add popover (next candidates); or touch any screen outside the Palette/Canvas. **Slice 3 — Floating Toolbar and Quick-Add popover.** - **Floating Toolbar**: replaced its five Dashicons (Copy/Paste/Duplicate/ Settings/Delete) with purpose-drawn inline SVGs, matching the search icon's stroke style. The Duplicate action's small "+" badge is now a real solid circle (was a bare mini-dashicon overlapping the copy icon, hard to read at that size) with a border matching the toolbar's own dark chip color, so it reads as a badge rather than visual noise. Added a subtle icon scale-up on button hover for tactile feedback, matching the same micro-interaction pattern used on palette items. - **Quick-Add popover**: was missing any entrance animation at all (previously just appeared instantly, inconsistent with every other popover/panel in the builder, which do animate in) — added one using the existing `--fc-motion-base`/`--fc-ease` tokens, collapsed under `prefers-reduced-motion` like the rest. Same search-icon/focus-ring/ token treatment as the main Field Palette's search bar (slice 2), so the two search inputs now look and behave identically instead of two independently-drifted implementations. - Extended the `prefers-reduced-motion` block to cover every new transition/animation introduced across slices 2 and 3 (previously only covered the Floating Toolbar's entrance and a handful of canvas elements). - **Still not attempted**: the Floating Toolbar's dark chip color (`#172033`) remains a literal, one-off value rather than a token — it's intentionally distinct from the rest of the light-surface UI (a dark-chip-on-light-canvas pattern), and inventing a new shared token for a single component wasn't warranted here. Icon-set replacement is still the same open item as slice 2. **Slice 4 — the real top navigation (`assets/css/admin.css`'s `.chargeforms-topbar*`) and the global Ctrl+K search/command palette.** This is the actual "dashboard tabs" surface (Forms/Entries/Reports/ Payments/Global Settings/Tools/Integrations/Support) — distinct from the builder's internal Field Palette group filters covered in slice 2, and the highest-visibility screen in the whole plugin since it's on every page. - Tokenized remaining literals in the top nav (`#fff` → `--fc-surface`, `border-radius: 8px/999px/7px/6px` → the real radius scale, `box-shadow: var(--fc-card-shadow)` → `--fc-shadow-sm`, untimed `0.18s`/`0.15s` transitions → `--fc-motion-base`/`--fc-motion-fast`). - Nav tabs: the active-tab transition previously animated background/ color but not the shadow that appears with it, so the gradient pill's elevation popped in instantly while everything else eased — now all four properties (background, color, box-shadow, transform) transition together. Added a small press-down micro-interaction on click. - Search trigger button: added a real focus-visible ring (previously keyboard-focusing it showed no visible state at all beyond the browser's default outline) and a hover shadow lift. - **The Ctrl+K command palette modal had no entrance animation at all** — it and its backdrop just appeared via `[hidden]` toggling, the only overlay/popover left in the plugin without one after slices 2-3. Added a backdrop fade plus a modal fade+scale-in, both collapsing under `prefers-reduced-motion`. - **Not attempted this slice**: the search RESULTS list styling, the delete-confirmation modal, and the rest of `admin.css` (Forms/Entries/ Reports/Settings/Tools/Integrations/Support screen bodies, not just the shared topbar/search chrome) — real work, next candidates. **Slice 5 — the shared modal component and search-results list** (the two items slice 4 explicitly deferred). - The shared `.chargeforms-modal`/`.chargeforms-modal-overlay` component (used by every "Are you sure?" / Actions modal site-wide, including the delete-confirmation dialog) already had entrance animations — verified this rather than assuming, since slice 4 initially suspected it might not. Tokenized its literals (`#fff` → `--fc-surface`, `border-radius: 12px` → `--fc-radius-xl`, its box-shadow → `--fc-shadow-xl`, untimed durations → `--fc-motion-base`/`--fc-motion-slow`) and added it to the `prefers-reduced-motion` block, which it was missing. - Search-results row: tokenized its radius and transition timing to match the rest of the palette. - **Still not attempted**: Forms/Entries/Reports/Global Settings/Tools/ Integrations/Support screen BODIES (tables, cards, forms) — everything covered through slice 5 has been shared chrome (topbar, search, modals) that appears on every screen, not the screen-specific content underneath it. That's genuinely the next, larger body of work. **Slice 6 — Forms list screen (first real screen body, first thing anyone sees after the topbar): empty states and the Active/Inactive toggle.** - **Empty-state icon**: a bare 40px Dashicons glyph blown up to that size reads as pixelated/crude — gave it the same "icon chip" treatment (a colored circle behind a modestly-sized glyph) the builder's canvas empty-state already used, instead of just scaling the raw icon font. Applied consistently to both the Forms list's empty state and the Entries screen's (which had its own separate, drifted override with the same crude-scaling problem — removed the duplicate override so both now share one consistent treatment instead of two). - **Active/Inactive toggle** (every row, Forms list): had zero hover feedback at all despite being clickable — added a hover state on the track (darkens toward success green when already on, lightens toward a visible gray when off) and a press micro-interaction on the thumb. Tokenized remaining literals (`#fff`, `border-radius: 999px/50%`, untimed `0.15s ease`) to match. - **Still not attempted**: the Forms table itself (row styling, the hover-reveal row-actions row, column treatment), and every other screen body listed above. The Vue-rebuilt Forms List (`assets/src/vue-admin/forms-list/`) is a SEPARATE component tree from this PHP fallback table and needs its own pass — not covered by anything in this slice. **Slice 7 — the `wp-list-table` used by every plugin screen with a data table** (Forms, Entries, Activity Logs, API Logs — shared CSS, one fix covers all of them). - Tokenized the table shell's remaining literals (`border-radius: 8px` → `--fc-radius-lg`, its box-shadow → `--fc-shadow-sm`) and the untimed `0.1s ease` row-hover and row-actions-reveal transitions → `--fc-motion-fast`/`--fc-ease`. - The striped-row tint (`#fafbfd`) is now derived from the real `--fc-bg` token via `color-mix()` instead of an independently-chosen hex value that happened to look similar. - **Still not attempted**: this was a shared-shell fix, not a per-screen redesign — Entries/Reports/Global Settings/Tools/Integrations/Support still need their own screen-specific treatment (stat cards, filter bars, form layouts unique to each), and the icon system and dark mode remain the two largest deferred items overall. **Slice 8 — the stat-tile component (Entries + Reports Key Metrics rows) and the list toolbar's search/filter bar (Forms + Entries).** - **Stat tiles**: tokenized `#fff` → `--fc-surface`, `border-radius: 10px` → `--fc-radius-lg`, and its hover-lift transition timing (`--fc-motion-fast`, matching the same "hover feedback should feel near-instant" treatment used everywhere else this pass touched). - **List toolbar search box and filter selects**: neither had ANY focus transition — the border/box-shadow change on focus snapped instantly. Added smooth transitions and widened the focus ring from a 1px outline to the same `0 0 0 3px var(--fc-primary-50)` ring used on every other input this pass has touched (palette search, quick-add search, search trigger button), so focus states now read consistently across the entire plugin rather than differing input-by-input. Added a hover state on filter `