Skip to content

README.md

Latest commit

 

History

History
314 lines (235 loc) · 10 KB

README.md

File metadata and controls

314 lines (235 loc) · 10 KB

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)