css-base

A modern CSS design system library targeting the latest Chrome and Edge browsers. Built exclusively with cutting-edge CSS features — no preprocessor, no build step required.

Browser support

• Chrome 125+
• Edge 125+

Note: CSS @function and attr() features require Chrome 139+ / Edge 139+

File structure

dist/
  app.css          Entry point — import this file only
  theme.css        Default theme values (font, colors)
  base.css         HTML resets and font defaults
  variables.css    Spacing scale and size scale
  tokens.css       Semantic tokens (padding, margin, radius, motion, z-index)
  typography.css   Font families, sizes, weights, line heights
  functions.css    CSS @functions for color manipulation (Chrome 139+)
  palette.css      Colors, surfaces (computed), shadows (OKLCH)
  components.css   Base components (headings, buttons, inputs, cards, alerts)
  utilities.css    Utility classes for layout, spacing, color
  attr.css         Dynamic styling via attr() (Chrome 139+)
  reset.css        HTML resets and base styles
  metadata.json    Machine-readable index for IDE tooling

Demo skins

The repository ships 10 static demo pages in dist/demo/ to prove that @medyll/css-base can be re-skinned with token overrides only.

• Demo hub: dist/demo/index.html
• Included skins: Netflix, Amazon, WhatsApp, Windows 11, macOS, Spotify, Slack, GitHub, Dashboard, Terminal
• Skin authoring guide: dist/demo/SKINNING.md
• Starter template: dist/demo/skin-template.css

Each demo loads only app.css plus a local skin.css. No component markup forks and no library source changes are required.

Installation

pnpm add @medyll/css-base
# or
npm install @medyll/css-base
# or
yarn add @medyll/css-base

Usage

In your CSS entry point:

@import "@medyll/css-base";

Or in HTML:

<link rel="stylesheet" href="node_modules/@medyll/css-base/dist/app.css">

Import specific layers:

@import "@medyll/css-base/theme";
@import "@medyll/css-base/base";
@import "@medyll/css-base/reset";
@import "@medyll/css-base/variables";
@import "@medyll/css-base/tokens";
@import "@medyll/css-base/typography";
@import "@medyll/css-base/palette";
@import "@medyll/css-base/components";
@import "@medyll/css-base/utilities";
@import "@medyll/css-base/attr";

Layer architecture

reset < tokens < theme < components < utilities

| Layer | Contents | |-------|---------| | reset | Browser reset, base HTML element defaults | | tokens | Spacing scale, semantic tokens, typography variables | | theme | Color palette, surfaces, light/dark via light-dark() | | components | Styled elements: buttons, inputs, cards, alerts, tables | | utilities | Utility classes + attr() data-attribute utilities |

Styles in later layers win over earlier ones. Your application styles placed outside any layer win over everything — no specificity hacks needed.

To extend within the cascade:

@import "@medyll/css-base";
@layer my-overrides { /* wins over utilities */ }

CSS features used

| Feature | Purpose | |---|---| | @layer | Cascade control | | CSS Nesting | Component scoping | | color-mix() | Tints, shades, alpha variants | | light-dark() | Automatic dark mode | | Relative color syntax (hsl/oklch from) | Computed hover and muted colors | | CSS Anchor Positioning | Tooltip and popover placement | | text-box-trim / text-box-edge | Precise typographic spacing | | subgrid | Aligned card layouts | | text-wrap: balance | Balanced multiline text | | @function (CSS Values Level 5) | Reusable color transformation functions |

Token system

Design tokens are defined as CSS custom properties on :root inside the theme files.

Theme variables (customization)

Override these variables in theme.css to customize the design system:

:root {
  /* Font properties */
  --default-font-size: 1rem;        /* Base font size (default: 0.875rem) */
  --default-leading: 1.6;           /* Base line height (default: 1.5) */
  --default-font-weight: 400;       /* Base font weight (default: 400) */
  --default-tracking: 0.02em;       /* Base letter spacing (default: 0) */

  /* Text colors (OKLCH format) */
  --default-color-text-light: oklch(0.2 0.02 265);  /* Light mode text */
  --default-color-text-dark: oklch(0.95 0.01 265);  /* Dark mode text */

  /* Surface colors (OKLCH format) */
  --default-color-surface-light: oklch(0.98 0.01 265);  /* Light mode background */
  --default-color-surface-dark: oklch(0.15 0.01 265);   /* Dark mode background */
}

Spacing tokens

Spacing — --gutter-xs through --gutter-3xl, with semantic aliases --pad-* and --marg-*

Typography — font families (--font-sans, --font-mono, --font-serif), size scale --text-xs (11px) to --text-5xl (48px), weights --font-normal → --font-black (900), line heights, letter spacing

Colors — --color-primary, --color-surface, --color-text, --color-border, status colors (--color-success, --color-warning, --color-critical, --color-info), and their computed variants

Motion — duration presets (--duration-fast/normal/slow/slower), easing functions, transition presets

Layout — z-index scale, --header-height, --sidebar-width, scrollbar dimensions

Dark mode

Dark mode is handled automatically via light-dark() and color-scheme. No class toggle required.

Manual override: Set data-theme attribute on <html> or <body> to force a specific mode:

<!-- Force light mode -->
<html data-theme="light">

<!-- Force dark mode -->
<html data-theme="dark">

<!-- Auto (default) - follows system preference -->
<html>

Your app's JavaScript controls the attribute based on user preference:

// Toggle dark mode
document.documentElement.setAttribute('data-theme', 'dark');

// Toggle light mode
document.documentElement.setAttribute('data-theme', 'light');

// Reset to auto (system preference)
document.documentElement.removeAttribute('data-theme');

Utilities

The utility layer provides single-purpose classes for layout, spacing, typography, color, and hover variants:

• Layout: flex, grid, block, hidden, and alignment helpers
• Spacing: margin and padding scale matching the token system
• Typography: size, weight, color, and text-wrap helpers
• Color: background and text color variants via color-mix()
• Interactive: hover:bg-*, hover:text-*, group hover support
• Ring / focus: ring-* classes for focus indicators

Responsive utilities

Use breakpoint prefixes for responsive styles:

| Prefix | Min-width | |--------|-----------| | sm: | 640px | | md: | 768px | | lg: | 1024px | | xl: | 1280px | | 2xl: | 1536px |

Example: <div class="flex md:grid lg:flex">

Components

Pre-styled components available out of the box:

• Cards: .card, .card-header, .card-body, .card-footer
• Alerts: .alert, .alert-info, .alert-success, .alert-warning, .alert-error
• Badges: .badge, .badge-primary, .badge-success, .badge-warning, .badge-error, .badge-neutral
• Tables: .table, .table-striped, .table-compact (wrapped in .table-container)

Dynamic Styling with attr() (Chrome 139+)

The attr.css layer enables dynamic styling directly via HTML attributes — no classes needed. These attr-utilities leverage the CSS attr() function for runtime property values.

attr-utilities reference

| Attribute | Values | Default | |-----------|--------|---------| | data-rotate | Any number (deg) | 0deg | | data-opacity | 0–1 (number) | 1 | | data-scale | Any number | 1 | | data-columns | Any integer | 1 | | data-rows | Any integer | 1 | | data-subgrid | (boolean) | — | | data-elevation | xs, sm, md, lg, xl, 2xl | md | | data-inset | xs, sm, md, lg, xl, 2xl | — | | data-ratio | square, portrait, landscape, video, ultrawide, golden | — | | data-zindex | dropdown, overlay, modal, toast | — | | data-pad | xs to 3xl | — | | data-margin | xs to 3xl | — | | data-radius | sm, md, lg, xl, full | — | | data-text | xs to 2xl | — | | data-weight | normal, medium, semibold, bold | — | | data-color | primary, secondary, success, warning, error, info, muted | — | | data-bg | surface, surface-alt, surface-raised, primary, secondary, success, warning, error, info | — | | data-gap | xs to 3xl | — | | data-blur | sm, md, lg, xl | — | | data-border | none, sm, md, lg | — | | data-translate-x | Any number (px) | 0px | | data-translate-y | Any number (px) | 0px |

Examples

<!-- Rotation -->
<div data-rotate="45">Rotated 45°</div>

<!-- Opacity -->
<div data-opacity="0.5">50% opaque</div>

<!-- Elevation -->
<div data-elevation="lg">Large elevation</div>

<!-- Inset (sunken) -->
<div data-inset="md">Sunken element</div>

<!-- Scale -->
<div data-scale="1.1">Scaled 110%</div>

<!-- Grid Columns & Rows -->
<div class="grid" data-columns="3" data-rows="2">
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
  <div>Item 4</div>
  <div>Item 5</div>
  <div>Item 6</div>
</div>

<!-- Subgrid (nested grids align with parent) -->
<div class="grid" data-columns="3">
  <div class="card" data-subgrid>
    <div>Header</div>
    <div>Content</div>
    <div>Footer</div>
  </div>
</div>

<!-- Aspect Ratio -->
<div data-ratio="video">16:9 video container</div>
<div data-ratio="square">1:1 square</div>
<div data-ratio="golden">Golden ratio</div>

<!-- Combined -->
<div data-rotate="6" data-opacity="0.95" data-elevation="lg" data-scale="1.05">
  Dynamic card
</div>

Accessibility

• :focus-visible for keyboard focus indicators
• prefers-reduced-motion support
• prefers-contrast: more support for high contrast mode

Accessibility

• :focus-visible for keyboard focus indicators
• prefers-reduced-motion support
• prefers-contrast: more support for high contrast mode

Author: Lebrun Meddy (@medyll)