@paradox-design/styles

The global style layer of Paradox Design System — reset, base, typography, layout primitives, utilities and a11y. Works independently of the components — you can use it in a project without a single web component.

Installation

npm install @paradox-design/tokens @paradox-design/styles

Install @paradox-design/tokens explicitly, even though it is already a dependency of this package. Styles do not import the tokens themselves — your code does (below), and strict package managers such as pnpm only resolve imports of direct dependencies.

Upgrade all @paradox-design/* packages together, to their latest versions. In 0.x a minor release may rename tokens; mixing minors leaves some variables undefined.

Import order

@import '@paradox-design/tokens/css'; /* 1. primitive + semantic tokens */
@import '@paradox-design/themes/css/default'; /* 2. theme                        */
@import '@paradox-design/styles'; /* 3. styles                       */

⚠️ Styles must come after tokens and the theme. They contain only var(--pdx-…); without the earlier definitions they resolve to empty values.

Use @paradox-design/tokens/css, not tokens/css/primitive alone. Styles rely on semantic tokens — spacing, typography, radius, elevation, focus — that a theme does not define, because a theme overrides only colors.

Layers

| File | What it does | When to skip it | | ---------------- | ------------------------------------------------------------ | ------------------------------------ | | reset.css | normalizes browsers | when you have your own reset | | base.css | styles HTML elements using tokens | when you style with classes only | | typography.css | .pdx-heading-*, .pdx-body-* classes | rarely | | layout.css | .pdx-stack, .pdx-cluster, .pdx-grid, .pdx-sidebar | when you have your own layout system | | utilities.css | spacing, flex and radius classes — generated from tokens | when you use Tailwind | | a11y.css | .pdx-visually-hidden, .pdx-skip-link, focus ring | never |

Selective import:

@import '@paradox-design/styles/reset';
@import '@paradox-design/styles/a11y';

Why there is no 12-column grid

Column grids were a workaround for the lack of flexbox and grid. Today .pdx-grid does the same with repeat(auto-fit, minmax(…)) — no classes in the HTML and no hard-coded breakpoints. The number of columns follows the available width, not whatever someone typed into col-md-4 six months ago.

Logical properties, not physical ones

Utilities use margin-inline-start, not margin-left:

| Class | Property | | ------------- | --------------------- | | .pdx-mi-md | margin-inline | | .pdx-mis-md | margin-inline-start | | .pdx-mbs-md | margin-block-start | | .pdx-pie-sm | padding-inline-end |

In RTL languages the layout flips by itself — no separate stylesheet and no [dir='rtl'] in the code.

Layout primitives

Each one is configured with a variable instead of piling up modifier classes:

.my-section {
  --pdx-stack-gap: var(--pdx-spacing-xl);
}

| Class | Variables | | -------------- | ----------------------------------------------------------------------- | | .pdx-stack | --pdx-stack-gap | | .pdx-cluster | --pdx-cluster-gap, --pdx-cluster-align | | .pdx-grid | --pdx-grid-min, --pdx-grid-gap | | .pdx-sidebar | --pdx-sidebar-width, --pdx-sidebar-gap, --pdx-sidebar-content-min | | .pdx-ratio | --pdx-ratio | | .pdx-clamp | --pdx-clamp-lines |

Accessibility

<a class="pdx-skip-link" href="#main">Skip to content</a> <span class="pdx-visually-hidden">Opens in a new tab</span>

🔴 Do not replace .pdx-visually-hidden with display: none. That also removes the element from the accessibility tree — the exact opposite of the intent.

The focus ring uses :focus-visible, not :focus — otherwise the outline would appear after a mouse click, users would report it as a bug, and someone would "fix" it with outline: none.

Quality checks

pnpm build validates every use of var(--pdx-…) against the real tokens.

ℹ️ A typo in a CSS variable name does not cause an error — it causes an empty style. Without this validation --pdx-color-text-link-hovr would pass review and surface in production. Variables with a fallback value (var(--pdx-stack-gap, …)) are user configuration points and do not have to be tokens.

Utilities are generated from the token scale — add a spacing step and the class appears on its own; remove it and the class disappears. A hand-written list would drift at the first change.

License

MIT © Paradox Software