Skip to content

feat(styles)!: generate theme variables from @gravity-ui/uikit-themer - #2745

Open
kseniya57 wants to merge 1 commit into
mainfrom
migrate-to-gravity-themer
Open

feat(styles)!: generate theme variables from @gravity-ui/uikit-themer#2745
kseniya57 wants to merge 1 commit into
mainfrom
migrate-to-gravity-themer

Conversation

@kseniya57

@kseniya57 kseniya57 commented Jul 14, 2026

Copy link
Copy Markdown
Contributor

Summary

Replaces the hand-maintained SCSS theme sources (light / dark / light-hc / dark-hc, plus the base / line / private / sfx / system / text partials and their typography/border-radius tokens) with theme artifacts generated from @gravity-ui/uikit-themer. Color tokens, typography metrics and the border-radius scale now come from a single upstream source of truth instead of being copied by hand.

What changed

  • Generated theme artifacts (committed):
    • styles/themes/default.generated.css — the default light/dark theme, copied verbatim from themer's prebuilt styles/default.css.
    • styles/themes/hc.generated.css — the high-contrast theme. Themer has no HC concept (Theme = 'light' | 'dark'), so its higher-contrast
      palette + utility mappings live in the repo-owned seed styles/themes/theme-data/hc.ts, merged onto DEFAULT_THEME and relabeled onto the
      -hc selectors.
    • Both files are committed (not imported from node_modules at build time) so a themer version bump surfaces as a reviewable token
      diff, and CI's empty-diff check catches drift.
  • Generation script scripts/generate-theme-scss.mjs, exposed as npm run generate:theme (run via tsx, since the HC seed is a TS
    module). Normalizes color literals to themer's space syntax (rgb(a b c / d)) so HC matches the shipped default.css.
  • styles/styles.scss now @uses the two generated CSS files directly; .g-root keeps only the repo-owned tokens themer doesn't model
    (spacing, scrollbar width, focus radius, flow direction, typography extras).
  • styles/themes/common/typography.scss trimmed to only the tokens themer (v1) can't express: the accent font-weight, the composite
    --g-text-*-font shorthands, and the base font-* declarations on .g-root. Font families, per-group weights, and per-variant
    sizes/line-heights now come from themer.
  • Removed the old per-theme SCSS trees (styles/themes/{light,dark,light-hc,dark-hc}/*, styles/themes/_index.scss) and the
    border-radius block from common/_index.scss.
  • Tooling: added @gravity-ui/uikit-themer and tsx devDependencies; tsconfig.json now includes styles/themes/theme-data/**/*.ts;
    CI gained a step that regenerates the theme and fails if the working tree drifts.
  • Docs: docs/theming.md updated to reflect the generated-theme workflow.
  • Screenshot baselines updated for the minor, expected rendering deltas (a handful of Playwright reference PNGs).

Why

  • Single source of truth for color/typography/radius tokens — no more hand-copying values from upstream.
  • Version bumps become reviewable, diff-able token changes rather than opaque updates.
  • CI guards against manual edits and stale artifacts.

Notes for reviewers

  • The color diff vs. the previous hand-written themes is limited to the accepted DEFAULT_THEME deltas plus a pure rgba(a,b,c,d)rgb(a b c / d) syntax swap

Migration notes (for consumers)

No public CSS variable is removed or renamed — every var(--g-color-*) usage
keeps working, so no code changes are required for apps that consume tokens
through variables and don't pin exact color literals.

This release does change the rendered theme, so downstream apps should:

  • Regenerate visual/screenshot baselines. Rendered colors change slightly.
    The private solid shades shift by ±1
    (imperceptible).
  • Update snapshot tests that assert the literal string of a token — e.g.
    rgba(0, 0, 0, 0.5) is now rgb(0 0 0 / 0.5) (same computed color).
  • Adjust any tooling that parses the rgba(...) literal of a token value;
    values now use the space/slash rgb(...) syntax (Baseline in all supported
    browsers).

The newly added tokens are safe/additive: --g-color-private-*-550 solids and
the 2%-alpha shades (*-20, black-70, …).

@sourcery-ai

sourcery-ai Bot commented Jul 14, 2026

Copy link
Copy Markdown
Contributor

Reviewer's Guide

Generates SCSS theme variables from @gravity-ui/uikit-themer instead of handwritten theme partials, centralizing light/dark/HC colors, border radii, and core typography into a build-generated _generated.scss file, wiring it into the theme entrypoint, and adding scripts/CI/docs to keep the artifact reproducible and documented.

File-Level Changes

Change Details Files
Generate SCSS theme tokens from @gravity-ui/uikit-themer into a committed _generated.scss and wire it as the source of truth for all theme variants.
  • Add scripts/generate-theme-scss.mjs to call uikit-themer DEFAULT_THEME, merge in HC data, normalize color syntax to rgb(... / ...), and emit five SCSS mixins for common/light/dark/light-hc/dark-hc.
  • Introduce styles/themes/_generated.scss as the generated artifact containing all themer-owned tokens (colors, border radii, core typography) for each theme variant.
  • Refactor styles/themes/_index.scss to consume generated.g-themer-* mixins for each variant and layer repo-owned common tokens via a new g-theme-common mixin.
scripts/generate-theme-scss.mjs
styles/themes/_generated.scss
styles/themes/_index.scss
Define high-contrast theme seed data and tooling so HC remains repo-owned but generated through themer.
  • Add scripts/bootstrap-hc-theme.mjs to extract HC base/private/utility colors from compiled styles.css and store them as a JSON seed.
  • Add styles/themes/theme-data/hc.json to hold HC palette and utility mappings used when generating HC variants.
  • Ensure generate-theme-scss.mjs builds HC themes by merging hc.json data with DEFAULT_THEME typography/borders.
scripts/bootstrap-hc-theme.mjs
styles/themes/theme-data/hc.json
scripts/generate-theme-scss.mjs
Trim repo-owned typography and common theme SCSS to only the pieces not modeled by themer, delegating core typography and border radii to the generated mixins.
  • Update styles/themes/common/typography.scss so its mixin only defines accent font weight, composite --g-text--font shorthands, and base font declarations, removing font-family/size/line-height variables now generated by themer.
  • Adjust styles/themes/common/_index.scss to drop --g-border-radius- definitions and clarify in comments that border radii and core typography come from _generated.scss, while spacing/scrollbar/focus radius/flow direction remain repo-owned.
  • Update the main theme composition so common typography/spacing are applied via common.g-theme-common atop the generated tokens.
styles/themes/common/typography.scss
styles/themes/common/_index.scss
styles/themes/_index.scss
Remove legacy handwritten theme partials for each variant now superseded by generated tokens.
  • Delete per-variant token partials for light, dark, light-hc, and dark-hc (private/base/text/line/sfx/system) in styles/themes/**.
  • Rely exclusively on the generated mixins for color and core typography definitions across all themes.
styles/themes/dark-hc/_index.scss
styles/themes/dark-hc/base.scss
styles/themes/dark-hc/line.scss
styles/themes/dark-hc/private.scss
styles/themes/dark-hc/sfx.scss
styles/themes/dark-hc/system.scss
styles/themes/dark-hc/text.scss
styles/themes/dark/_index.scss
styles/themes/dark/base.scss
styles/themes/dark/line.scss
styles/themes/dark/private.scss
styles/themes/dark/sfx.scss
styles/themes/dark/system.scss
styles/themes/dark/text.scss
styles/themes/light-hc/_index.scss
styles/themes/light-hc/base.scss
styles/themes/light-hc/line.scss
styles/themes/light-hc/private.scss
styles/themes/light-hc/sfx.scss
styles/themes/light-hc/system.scss
styles/themes/light-hc/text.scss
styles/themes/light/_index.scss
styles/themes/light/base.scss
styles/themes/light/line.scss
styles/themes/light/private.scss
styles/themes/light/sfx.scss
styles/themes/light/system.scss
styles/themes/light/text.scss
Add verification, dependency, and documentation plumbing to support the new theming pipeline.
  • Introduce scripts/verify-theme-diff.mjs to compare two compiled styles.css files at the level of normalized custom property values, filtering out pure syntax changes.
  • Add npm scripts generate:theme and bootstrap:hc-theme to package.json and declare @gravity-ui/uikit-themer as a dependency.
  • Update CI workflow to enforce that running generate:theme produces no diff in styles/themes/_generated.scss.
  • Extend README.md and README-ru.md with notes about generated theme variables and links to new theming migration docs.
  • Add docs/theming-migration.md and docs/theming-migration-ru.md detailing the architecture, trade-offs, and consumer migration guidance.
scripts/verify-theme-diff.mjs
.github/workflows/ci.yml
package.json
package-lock.json
README.md
README-ru.md
docs/theming-migration.md
docs/theming-migration-ru.md
.husky/pre-commit

Possibly linked issues

  • #: PR implements the requested migration: theme CSS variables now generated from @gravity-ui/uikit-themer and wired into styles.

Tips and commands

Interacting with Sourcery

  • Trigger a new review: Comment @sourcery-ai review on the pull request.
  • Continue discussions: Reply directly to Sourcery's review comments.
  • Generate a GitHub issue from a review comment: Ask Sourcery to create an
    issue from a review comment by replying to it. You can also reply to a
    review comment with @sourcery-ai issue to create an issue from it.
  • Generate a pull request title: Write @sourcery-ai anywhere in the pull
    request title to generate a title at any time. You can also comment
    @sourcery-ai title on the pull request to (re-)generate the title at any time.
  • Generate a pull request summary: Write @sourcery-ai summary anywhere in
    the pull request body to generate a PR summary at any time exactly where you
    want it. You can also comment @sourcery-ai summary on the pull request to
    (re-)generate the summary at any time.
  • Generate reviewer's guide: Comment @sourcery-ai guide on the pull
    request to (re-)generate the reviewer's guide at any time.
  • Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
    pull request to resolve all Sourcery comments. Useful if you've already
    addressed all the comments and don't want to see them anymore.
  • Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
    request to dismiss all existing Sourcery reviews. Especially useful if you
    want to start fresh with a new review - don't forget to comment
    @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

  • Enable or disable review features such as the Sourcery-generated pull request
    summary, the reviewer's guide, and others.
  • Change the review language.
  • Add, remove or edit custom review instructions.
  • Adjust other review settings.

Getting Help

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey - I've left some high level feedback:

  • The regex-based splitBlocks/extractBlock helpers in the generator and HC bootstrap scripts are tightly coupled to the current .g-root selector shapes; consider centralizing these patterns or at least failing loudly if a selector is missing (e.g. explicit checks with helpful errors) to make future selector refactors safer.
  • Since _generated.scss is a large committed artifact, it may be worth adding a short note near the mixin definitions (or in the README) about how to consume g-theme-common vs g-themer-* mixins correctly, to avoid downstream themes accidentally omitting the repo-owned common tokens.
Prompt for AI Agents
Please address the comments from this code review:

## Overall Comments
- The regex-based `splitBlocks`/`extractBlock` helpers in the generator and HC bootstrap scripts are tightly coupled to the current `.g-root` selector shapes; consider centralizing these patterns or at least failing loudly if a selector is missing (e.g. explicit checks with helpful errors) to make future selector refactors safer.
- Since `_generated.scss` is a large committed artifact, it may be worth adding a short note near the mixin definitions (or in the README) about how to consume `g-theme-common` vs `g-themer-*` mixins correctly, to avoid downstream themes accidentally omitting the repo-owned common tokens.

Sourcery is free for open source - if you like our reviews please consider sharing them ✨
Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.

@gravity-ui

gravity-ui Bot commented Jul 14, 2026

Copy link
Copy Markdown
Contributor

Preview is ready.

@kseniya57 kseniya57 linked an issue Jul 14, 2026 that may be closed by this pull request
1 task
@gravity-ui

gravity-ui Bot commented Jul 14, 2026

Copy link
Copy Markdown
Contributor

🎭 Component Tests Report is ready.

@kseniya57
kseniya57 force-pushed the migrate-to-gravity-themer branch 9 times, most recently from 6847f41 to d999004 Compare July 16, 2026 09:26
@kseniya57
kseniya57 force-pushed the migrate-to-gravity-themer branch 3 times, most recently from 8be06fd to e0d6a02 Compare July 22, 2026 12:07
@amje amje changed the title feat(styles): generate theme variables from @gravity-ui/uikit-themer feat(styles)!: generate theme variables from @gravity-ui/uikit-themer Jul 22, 2026
@kseniya57
kseniya57 force-pushed the migrate-to-gravity-themer branch from e0d6a02 to ca7455e Compare July 22, 2026 13:36
@kseniya57
kseniya57 force-pushed the migrate-to-gravity-themer branch from ca7455e to 19d2aa0 Compare July 26, 2026 14:04
@kseniya57
kseniya57 force-pushed the migrate-to-gravity-themer branch from 19d2aa0 to b18b224 Compare August 5, 2026 04:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Migrate to the theme from the @gravity-ui/uikit-themer

1 participant