dusk-network / dusk-network/duskit

refactor(components, css)!: introduce namespace prefix for all CSS variables

Open
#262 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

need:feedback
Dominant language
JavaScript
Stars
2
Forks
0
PR merge metrics
No merged PRs in 30d

Description

Context and Motivation:
Currently, our CSS tokens and variables are defined in the global scope without any library-specific namespace (e.g., --primary-color, --z-modal). Because the CSS custom properties namespace is global and extremely permissive, this approach exposes consumers of the @duskit library to severe risks of styling collisions. If a consumer's project or another third-party library defines a variable with the same exact name, our internal components will silently inherit the external value, leading to unpredictable UI breakages and layout issues.

To ensure encapsulation, prevent regression bugs, and provide a robust design system, we must prefix all exported and internal CSS variables.

Proposed Implementation:

  1. Rename all existing CSS variables across the entire monorepo to include a library-specific prefix. We need to decide between two viable naming conventions:
    • Option A (Explicit): --duskit-* (e.g., --duskit-z-modal, --duskit-color-primary). This is highly readable, self-documenting, and leaves no room for ambiguity.
    • Option B (Compact): --dk-* (e.g., --dk-z-modal, --dk-color-primary). This reduces code verbosity and saves a few bytes, but might conflict with other projects using the same acronym.
    • Option C (my preference): --dusk-*. Same advantages as option A and we keep consistency with the CSS class names prefixes.
  2. Update all variable definitions inside the @duskit/css package.
  3. Update all component stylesheets inside the @duskit/components package to consume the newly prefixed tokens.
  4. Document this as a breaking change in the release notes.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by inventorying CSS variable definitions in the @duskit/css package and their consumers in the @duskit/components package. Resolve the proposed prefix convention before updating all definitions and references across the monorepo. Done means the variables use the chosen namespace consistently and the breaking change is documented in the release notes.

Written by the indexing model from the issue text.

Assessment

Tech stack
css, javascript
Domain
design, documentation, frontend
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.