From 2b355ee76f8cb0c5903573f1105bce47607c123f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pawe=C5=82=20Kuna?= <1282324+codecalm@users.noreply.github.com> Date: Tue, 8 Sep 2026 23:14:52 +0200 Subject: [PATCH] Align core, shared and preview with the design-system skill (#3010) --- .agents/skills/design-system/SKILL.md | 33 +++- .../skills/design-system/rules-of-thumb.md | 54 ++++-- .changeset/design-audit-core-added.md | 5 + .changeset/design-audit-core-colors.md | 5 + .changeset/design-audit-core-recipes.md | 5 + .changeset/design-audit-core-removed.md | 5 + .changeset/design-audit-decisions.md | 5 + .changeset/design-audit-inbox.md | 5 + .changeset/design-audit-preview.md | 5 + core/scss/_variables.scss | 34 ++-- core/scss/ui/_avatars.scss | 10 +- core/scss/ui/_badges.scss | 4 +- core/scss/ui/_buttons.scss | 8 +- core/scss/ui/_calendars.scss | 4 +- core/scss/ui/_cards.scss | 32 ++-- core/scss/ui/_carousel.scss | 4 +- core/scss/ui/_chat.scss | 2 +- core/scss/ui/_dropdowns.scss | 7 +- core/scss/ui/_forms.scss | 22 ++- core/scss/ui/_icons.scss | 6 +- core/scss/ui/_legend.scss | 2 +- core/scss/ui/_lists.scss | 6 +- core/scss/ui/_loaders.scss | 4 +- core/scss/ui/_markdown.scss | 2 +- core/scss/ui/_modals.scss | 2 +- core/scss/ui/_nav.scss | 35 +++- core/scss/ui/_pagination.scss | 25 ++- core/scss/ui/_patterns.scss | 5 +- core/scss/ui/_payments.scss | 2 +- core/scss/ui/_ribbons.scss | 4 +- core/scss/ui/_segmented.scss | 6 +- core/scss/ui/_signature.scss | 2 +- core/scss/ui/_stars.scss | 2 +- core/scss/ui/_steps.scss | 11 +- core/scss/ui/_switch-icon.scss | 8 +- core/scss/ui/_tags.scss | 2 +- core/scss/ui/_toasts.scss | 6 +- core/scss/ui/_type.scss | 13 +- core/scss/ui/forms/_form-check.scss | 2 +- core/scss/ui/forms/_form-colorinput.scss | 4 +- core/scss/ui/forms/_form-imagecheck.scss | 2 +- core/scss/ui/forms/_form-selectgroup.scss | 1 + docs/content/ui/components/list-group.mdx | 4 +- docs/content/ui/components/trending.mdx | 178 +++++++++++------- preview/pages/2-step-verification-code.astro | 4 +- preview/pages/2-step-verification.astro | 6 +- preview/pages/all-elements.astro | 168 ++++++++--------- preview/pages/card-gradients.astro | 6 +- preview/pages/cards-masonry.astro | 2 +- preview/pages/cookie-banner.astro | 4 +- preview/pages/dashboard-crypto.astro | 28 +-- preview/pages/datatables.astro | 79 ++++---- preview/pages/dropzone.astro | 6 +- preview/pages/email-inbox.astro | 127 ++++++------- preview/pages/faq.astro | 2 +- preview/pages/form-elements.astro | 108 +++++------ preview/pages/form-layout.astro | 38 ++-- preview/pages/illustrations.astro | 4 +- preview/pages/inline-player.astro | 2 +- preview/pages/logs.astro | 10 +- preview/pages/map-fullsize.astro | 4 +- preview/pages/maps-vector.astro | 2 +- preview/pages/marketing/about.astro | 14 +- preview/pages/marketing/real-estate.astro | 6 +- preview/pages/modals.astro | 2 +- preview/pages/navigation.astro | 2 +- preview/pages/onboarding.astro | 6 +- preview/pages/patterns.astro | 44 ++--- preview/pages/pay.astro | 4 +- preview/pages/payment-providers.astro | 2 +- preview/pages/pricing-table.astro | 16 +- preview/pages/profile.astro | 2 +- preview/pages/progress.astro | 10 +- preview/pages/screenshot.astro | 9 +- preview/pages/scroll-spy.astro | 2 +- preview/pages/settings.astro | 8 +- preview/pages/sortable.astro | 14 +- preview/pages/stars-rating.astro | 2 +- preview/pages/tasks-list.astro | 12 +- preview/pages/tour.astro | 14 +- preview/pages/trial-ended.astro | 2 +- preview/pages/users.astro | 4 +- preview/scss/_highlight.scss | 48 ----- preview/scss/demo.scss | 57 +++--- shared/components/cards/AuthLockCard.astro | 2 +- .../cards/AuthenticateAccount.astro | 2 +- shared/components/cards/BodyPlaceholder.astro | 2 +- shared/components/cards/CrmStats.astro | 4 +- shared/components/cards/EmptyTeam.astro | 4 +- shared/components/cards/GalleryPhoto.astro | 4 +- shared/components/cards/InvoiceCard.astro | 112 +++++------ shared/components/cards/Invoices.astro | 2 +- .../components/cards/MostVisitedPages.astro | 2 +- shared/components/cards/PricingCard.astro | 11 +- shared/components/cards/PricingPlan.astro | 14 +- shared/components/cards/ProfileContact.astro | 2 +- shared/components/cards/RecentActivity.astro | 4 +- shared/components/cards/SmallStats.astro | 2 +- shared/components/cards/SocialTraffic.astro | 2 +- shared/components/cards/Sponsor.astro | 4 +- shared/components/cards/TasksDue.astro | 5 +- shared/components/cards/TeamLeaderboard.astro | 2 +- shared/components/cards/TopDeals.astro | 4 +- shared/components/cards/Weather.astro | 2 +- shared/components/cards/Welcome.astro | 29 +-- shared/components/cards/YouWin.astro | 2 +- .../cards/charts/ActiveUsers2.astro | 2 +- .../cards/charts/PipelineFunnel.astro | 2 +- .../components/cards/charts/TotalUsers.astro | 2 +- shared/components/cards/form/Payment.astro | 8 +- .../components/cards/music/TracksList.astro | 4 +- .../components/cards/tables/Progressbg.astro | 7 +- shared/components/demo/DropdownMenuAll.astro | 2 +- shared/components/demo/MapVector.astro | 6 +- shared/components/demo/Table.astro | 4 +- shared/components/demo/ThemeSettings.astro | 2 +- shared/components/demo/Timeline.astro | 6 +- shared/components/demo/Toast.astro | 4 +- shared/components/forms/FormElements2.astro | 6 +- shared/components/forms/FormElements3.astro | 14 +- shared/components/forms/FormElements4.astro | 22 +-- shared/components/forms/FormElements5.astro | 16 +- .../layout/HeaderActionsButtons.astro | 9 +- .../layout/HeaderActionsPrint.astro | 2 +- shared/components/layout/HeaderProfile.astro | 2 +- .../marketing/sections/Counters.astro | 8 +- .../components/marketing/sections/Faq.astro | 2 +- .../marketing/sections/Features2.astro | 2 +- .../marketing/sections/Features3.astro | 2 +- .../marketing/sections/Pricing.astro | 2 +- .../marketing/sections/PricingBanner.astro | 2 +- .../marketing/sections/Subscribe.astro | 2 +- .../modals/AddTaskModalContent.astro | 2 +- .../modals/ChangePasswordModalContent.astro | 8 +- .../modals/ConfirmDeleteModalContent.astro | 16 +- .../modals/EditProfileModalContent.astro | 20 +- .../modals/NewEmailModalContent.astro | 4 +- .../modals/NewEventModalContent.astro | 10 +- .../modals/NewTaskModalContent.astro | 14 +- .../modals/ReportModalContent.astro | 4 +- .../modals/SignatureModalContent.astro | 2 +- .../components/modals/TeamModalContent.astro | 2 +- shared/components/navbar/Navbar.astro | 4 - shared/components/navbar/NavbarMenuItem.astro | 6 +- shared/components/navbar/NavbarSideApps.astro | 4 +- .../navbar/NavbarSideNotifications.astro | 6 +- shared/components/navbar/NavbarSideUser.astro | 2 +- shared/components/navbar/SidebarUser.astro | 2 +- shared/components/parts/Datagrid.astro | 4 +- shared/components/parts/Tasks.astro | 4 +- shared/components/parts/form/InputColor.astro | 2 +- shared/layouts/SettingsLayout.astro | 12 +- shared/ui/ChartRadial.astro | 6 +- shared/ui/InputGroup.astro | 6 +- shared/ui/ProgressDescription.astro | 6 +- shared/ui/Rating.astro | 2 +- shared/ui/SwitchIcon.astro | 2 +- shared/ui/Trending.astro | 2 +- 158 files changed, 1025 insertions(+), 947 deletions(-) create mode 100644 .changeset/design-audit-core-added.md create mode 100644 .changeset/design-audit-core-colors.md create mode 100644 .changeset/design-audit-core-recipes.md create mode 100644 .changeset/design-audit-core-removed.md create mode 100644 .changeset/design-audit-decisions.md create mode 100644 .changeset/design-audit-inbox.md create mode 100644 .changeset/design-audit-preview.md delete mode 100644 preview/scss/_highlight.scss diff --git a/.agents/skills/design-system/SKILL.md b/.agents/skills/design-system/SKILL.md index bb99d9ee6..0996d107a 100644 --- a/.agents/skills/design-system/SKILL.md +++ b/.agents/skills/design-system/SKILL.md @@ -117,7 +117,7 @@ migration plan removes it together with every `rgba(var(--X-rgb))` site, so buil | Body size / line | `0.875rem` (14px) / `1.25rem` (20px) | | Small / large body | `0.765625rem` (12.25px; `0.75rem` in 2.0, decision #4) / `1.09375rem` (17.5px) | | Weights | 400 body · 500 medium · 600 semibold · 300 display | -| Letter spacing | 0 | +| Letter spacing | 0, except `0.04em`: the `subheader()` mixin (`.subheader`, table heads, `.table-mobile` cell labels, `.dropdown-header`, `.datagrid-title`, `.page-pretitle`, `.hr-text`) and the sidebar section title, which writes the same value by hand | | Root font size | not set; `rem` follows the user's browser setting (WCAG 1.4.4) | ### Heading scale (size / line, both on the 4px grid) @@ -137,7 +137,9 @@ Heading margin-bottom is `--spacer` (8px). Headings and `strong` share the semib ### Where each weight is used - **400** body text, lead (lead is body-size in the secondary colour, not larger). -- **500** buttons, form labels, badges, `kbd`, card titles. +- **500** buttons, form labels, badges, `kbd`, card titles, modal and offcanvas titles, ribbons, + the chat bubble author, and the active item of a vertical nav, list or step (the active colour + already carries the state). - **600** headings, `strong`, navbar brand, alert links. ### Component text sizes @@ -146,12 +148,15 @@ Heading margin-bottom is `--spacer` (8px). Headings and `strong` share the semib | --- | --- | --- | --- | | Card title | h3 (16px) | 500 | heading colour | | Card subtitle | h4 (14px) when inline | 400 | secondary | +| Modal / offcanvas title | h3 (16px) | 500 | heading colour | | Page title | h2 (20px / 28px) | headings weight | | | Form label | h4 (14px), margin-bottom 8px | 500 | body | +| Fieldset legend as a label (`legend.form-label`) | inherits 14px (the reboot's bare `legend` is 24px) | 500 | body | +| Markdown prose (`.markdown`) | h3 (16px), blockquote 16px — long-form reading text is the one exception to the 14px content rule | 400 | body | | Form hint / feedback | `0.875em`, margin-top 4px | 400 | secondary | | Tooltip / popover body | small (12.25px) | | | | Badge | `0.857em` of parent (sm `0.714em`, lg `1em`) | 500 | | -| Sidebar section title | 12px | | | +| Sidebar section title | 12px, uppercase, tracked `0.04em` | 500 | navbar colour at 70% | | Code | `0.857em`, `gray-600` on `gray-100` (dark: `gray-400` on `gray-900`) | | | --- @@ -248,7 +253,7 @@ Rule of thumb: **controls 6px, containers 8px, small controls 4px.** A global ### Borders -- Width 1px; `wide` 2px (nav-bordered active, steps, modal status, progress ring). +- Width 1px; `wide` 2px (nav-bordered active, steps, modal status, progress ring, card status bar, blockquote rule). Components write `var(--border-width)`, not `1px`. - Colour: `--border-color-translucent` for cards, tables, dropdowns, alerts (blends on any background); `--border-color` for navbars, modals headers, list groups, tabs, popovers. - Hover on a control raises the border to `--border-active-color`. @@ -287,7 +292,11 @@ Every interactive component expresses the same five states with the same tokens: - Coloured buttons: filled `btn-X`, `btn-outline-X` (transparent, coloured border, fills on hover), `btn-ghost-X` (no border, tints on hover). - Nav variants: `pills` (active = `--active-bg` + primary text), `bordered` (2px primary - underline), `tabs` (surface bg + border), `underline` (2px, emphasis colour). + underline), `tabs` (surface bg + border), `underline` (2px, emphasis colour), `segmented` + (tertiary track with an inset 1px translucent ring; active = surface bg + `--border-color`; + sizes 32 / 40 / 48px, link gap 8px, lg 12px). +- Hover on a list, nav, pagination, action button or select-group item is `$hover-bg`; the + open state of a `form-help` popover and the checked select-group item are `--active-bg`. - Pagination active is the one place where a filled primary background is used for a selected item. @@ -302,8 +311,9 @@ Every interactive component expresses the same five states with the same tokens: | Collapse | `height 0.35s ease` | | Modal | `transform 0.3s ease-out`, slides down 16px; static backdrop scales 1.02 | | Progress bar | `width 0.6s ease` | -| Reveal on hover (`$transition-time`) | `0.3s` — list-group item actions, card options; an opacity fade, not a colour change | -| Icon animations | pulse 2s, tada 3s, rotate 3s | +| Reveal on hover (`$transition-time`) | `0.3s` — list-group item actions, card options, switch-icon fade/scale/flip; an opacity fade, not a colour change | +| Icon animations | pulse 2s, tada 3s, rotate 3s (`.icon-*`); `.btn-animate-icon-*` pulse/shake/tada 0.9s once on hover | +| Everything else | `$transition-time` 0.3s or `0.15s`; no other durations in `core/scss/ui` | `prefers-reduced-motion`: decorative loops (blink, pulse, tada, rotate, animated gradient, waves) are removed; loaders and indeterminate progress keep animating but at 3s so state is @@ -320,6 +330,8 @@ still visible. negative outer margin of a quarter. - Nav-link icons are the link colour at 50%, 80% on hover. - Filled variant only via `.icon-filled`. +- A toggle's two faces are `.switch-icon-a` (rest, inherits or `--secondary`) and `.switch-icon-b` + (on, a state colour — `SwitchIcon` takes it as `activeColor`). --- @@ -333,12 +345,17 @@ Places where the code contradicts its own rules, found on 2026-09-08 and decided | 2 | Sass `$spacer` = 16px but CSS `--spacer` = 8px. Headings use the 8px one, `card-img-overlay` and popover header use the 16px one. | `_variables.scss:341`, `layout/_root.scss` | **Fix in 2.0.** `--spacer` becomes 16px, equal to `$spacer`; headings get an explicit `--spacer-2`. Remap of the shipped `--tblr-spacer`: section 5 entry + upgrade guide. | planned 2.0 | | 3 | Small-element heights do not share a ladder: `btn-sm` 28 · `avatar-sm` 32 · tag/status 24. | buttons, inputs, avatars | **Fix in 2.0.** `btn-sm` (and with it `form-control-sm`, `form-select-sm`) goes to 32px: `$input-btn-padding-y-sm` 5px → 7px. The ladder becomes 24 / 32 / 40 / 48 / 56. Section 5 entry + upgrade guide. | planned 2.0 | | 4 | `$font-size-sm` is 12.25px, off the pixel grid; `h5` is 12px. | `_variables.scss:403` | **Fix in 2.0.** `$font-size-sm: 0.75rem`. Tooltips and popovers drop a quarter pixel. Short section 5 entry. | planned 2.0 | -| 5 | Two focus indicators: the ring everywhere, but `outline: 2px solid var(--primary)` in `_buttons.scss:294` and `_calendars.scss:73`. | buttons, calendars | **Fix.** Both go through `@include focus-ring()`; added to the scope of issue #2972. | tracked, #2972 | +| 5 | Two focus indicators: the ring everywhere, but `outline: 2px solid var(--primary)` on `.btn-action:focus-visible` (`_buttons.scss`), `.date-item:focus-visible` (`_calendars.scss`) and `.switch-icon:focus-visible` (`_switch-icon.scss`). | buttons, calendars, switch-icon | **Fix.** All three go through `@include focus-ring()`; added to the scope of issue #2972. | tracked, #2972 | | 6 | Hex literals outside the variable files: `--card-gradient-*`, `.card-cover` `#666`, `.card-note` `#fff7dd/#fff1c9`, calendar `#66758c` and `#fefeff`. | `ui/_cards.scss`, `ui/_calendars.scss` | **Fix, with one exception.** `.card-note`, `.card-cover` and the calendar get `light-dark()` tokens. The gradients stay literal: they are artwork, nobody rethemes them. | planned, no remap | | 7 | `$dropdown-header-color: $gray-600` and the `$dropdown-dark-*` family are not `light-dark()` pairs. | `_variables.scss` | **Fix in 2.0.** Header colour → `--secondary`. The `$dropdown-dark-*` Sass variables go; `.dropdown-menu-dark` keeps emitting through the dropdown tokens (v5 class, section 5 question 8). | planned 2.0 | | 8 | Tooltip 200px, popover 276px, modals 380/540/720/1140px and toast 350px are the only pixel widths. | `_variables.scss` | **Fix in 2.0.** Move to `rem` (12.5 · 17.25 · 23.75/33.75/45/71.25 · 21.875rem) so overlays scale with the user's font size. Section 5 entry. | planned 2.0 | | 9 | `icon-md` 40px and `icon-lg` 56px drop the stroke to 1; `icon-sm` keeps 1.5. | `ui/_icons.scss` | **Intended.** Rule: stroke 1.5 up to 24px, stroke 1 from 40px. Recorded in section 8. | closed, exception | | 10 | Table hover uses `--emphasis-color` at 7.5% while every other hover uses `$hover-bg` (`--secondary` at 8%). | `_variables.scss` table block | **Fix in 2.0.** `$table-hover-bg: $hover-bg`. Short section 5 entry. | planned 2.0 | +| 13 | Demo pages nest example cards inside a section card (`SectionCard` > `SectionCardBody` > `Card`), and `cards.astro` documents "Cards inside card"; rule 12 forbids a card in a card body. | `preview/pages/cards.astro` and every `SectionCard` page | **Intended.** The demo section wrapper is exempt from rule 12: it frames the examples, it is not product markup. The "cards inside card" demo stays. | closed, exception | +| 14 | `badge-outline` is forbidden by `.agents/rules/main.mdc` but shipped by `core/scss/ui/_badges.scss` and shown as the "Outline" demo on `badges.astro`. | `_badges.scss`, `badges.astro`, `job-listing.astro` | **Fix in 2.0.** The class is removed: it duplicates the soft `-lt` variant. Deprecate, section 5 entry, upgrade-guide line. | tracked, #3011 | +| 15 | Brand colour as UI chrome: the sponsor heart is `text-pink` inside `.btn` (`NavbarSide.astro`, `Sponsor.astro`), the marketing footer uses filled `btn-facebook` / `btn-x` / `btn-instagram` / `btn-linkedin`, and `SmallStats color="facebook"` fills a stat avatar. | `shared/components/**`, `shared/layouts/MarketingLayout.astro` | **Intended, for the brand only.** The sponsor heart and the social follow buttons keep their brand colour; everything else obeys rule 21. The one real violation was a decorative icon at rest, the favourite star in `ProfileContact`, which now inherits. A toggle's on-state (`.switch-icon-b`) is a separate, allowed pattern: it carries a state colour, not decoration. | closed, exception | +| 16 | Scroll containers carry an inline height: `ActivityCard` `height: 28rem`, `UsersListHeaders` `max-height: 35rem`, `NavbarSideApps` `max-height: 50vh`. | `shared/components/cards/ActivityCard.astro`, `UsersListHeaders.astro`, `navbar/NavbarSideApps.astro` | **Intended.** A scroll container's height is a per-instance layout choice, not a scale value, so it stays inline. Rule 18 records the exception. | closed, exception | + --- ## 10. What a review checks (summary) diff --git a/.agents/skills/design-system/rules-of-thumb.md b/.agents/skills/design-system/rules-of-thumb.md index 1e751e475..65451110c 100644 --- a/.agents/skills/design-system/rules-of-thumb.md +++ b/.agents/skills/design-system/rules-of-thumb.md @@ -12,6 +12,7 @@ A review cites a rule by number: "rule 16 — buttons go in `btn-list`". ### 1. Use 14px for content text Body copy, buttons, table cells and form values are 14px. 16px and above belong to headings. +Long-form prose inside `.markdown` is the one exception, at 16px (SKILL section 3). ```html @@ -28,7 +29,8 @@ Body copy, buttons, table cells and form values are 14px. 16px and above belong Only the first word and product names take a capital. Title Case reads as marketing, not UI. This covers all UI text: headings, card and page titles, subheaders, buttons, menu items and table headers. -Today: "Top Pages", "Payment Method", "Edit Profile" and about ten more card titles in preview. +Today: 0 in `preview/pages` and `shared/` after the sentence-case pass of 2026-09-08; what is left +capitalised is a product or proper name ("Tabler Icons", "Front-End Learning", "United States"). ```html @@ -43,7 +45,7 @@ Today: "Top Pages", "Payment Method", "Edit Profile" and about ten more card tit ### 3. Never use `fw-bold` Headings are semibold (600) and emphasised inline text is medium (500). 700 is not on the -weight scale. Today: 12 × `fw-bold` against 25 × `fw-medium` and 8 × `fw-semibold`. +weight scale. Today: 0 × `fw-bold`, 23 × `fw-medium`, 7 × `fw-semibold`. ```html @@ -57,8 +59,10 @@ weight scale. Today: 12 × `fw-bold` against 25 × `fw-medium` and 8 × `fw-semi ### 4. Never change letter spacing -`letter-spacing` is 0 everywhere. The only tracked text is `.subheader`, which the framework -styles itself. +`letter-spacing` is 0 everywhere. The only tracked text comes from the `subheader()` mixin, +which the framework applies itself: `.subheader`, table heads, `.table-mobile` cell labels, +`.dropdown-header`, `.datagrid-title`, `.page-pretitle` and `.hr-text`, plus the sidebar +section title, which writes the same `0.04em` by hand. Markup never adds tracking. ```html @@ -134,16 +138,16 @@ hand-written nesting must too.
| Product | -Sales | -Change | -
|---|---|---|
| Basic plan | -4,120 | -
- 12% |
-
| Pro plan | -2,043 | -
- -7% |
-
| Team plan | -986 | -
- 0% |
-
| Product | +Sales | +Change | +
|---|---|---|
| Basic plan | +4,120 | +
+
+ {' '}
+ 12% |
+
| Pro plan | +2,043 | +
+
+ {' '}
+ -7% |
+
| Team plan | +986 | +
+
+ {' '}
+ 0% |
+