Natcore LogoNatCorev2 — In Progress
v2 — In Progress

Natcore Design System v2

Natcore v2 is a design system that is meant to survive different stacks. The core surface area is CSS: tokens, utilities, and component styles applied through class names. If your product renders HTML, Natcore can style it.

Framework packages (React, Svelte, Vue) are optional. They exist for ergonomics, and they map to the same CSS contract. If something only works through a wrapper, that is a problem to fix, not a feature.

Requirements

  • Tailwind CSS is required.

  • OKLCH support is required.

What Natcore provides

  • Tokens as CSS variables for color, typography, spacing, radii, shadow, and motion. These tokens are the source of truth for visual decisions.

  • Utilities that compose directly on markup and stay compatible with Tailwind conventions. You should be able to build most UI by composing utilities, not by writing custom CSS for every screen.

  • Component styles implemented as reusable CSS patterns you opt into with classes. Modifiers are used to express intent consistently, rather than inventing one off class names.

  • A plugin used to customize and add themes, and to keep configuration centralized.

  • Framework packages and icons for React, Svelte, Vue, plus a separate icons package.

How you use Natcore

Import the core package from the same stylesheet where you import Tailwind. After that, usage is simple: write HTML, compose Tailwind utilities, and add Natcore utilities and component classes where you want Natcore behavior.

@import "@nataliebasille/natcore-design-system";

Installation and configuration details, including plugin setup, are documented on the Installation page.

Theming

Themes are selected via a data-theme attribute. Theme changes should not require markup changes. The point is that the same HTML can render correctly under different themes.

<html data-theme="dark"> ... </html>

Tokens are exposed as CSS variables. Example:

--color-primary-500

Conventions

Natcore stays coherent by being strict about vocabulary and naming. You should be able to scan markup and understand intent without reading implementation code.

Modifiers are the standard way to express variants and tones. Current vocabulary includes variantssolid, outline, ghost, soft, ghost-outlineand tones primary, secondary, accent, surface.

<div class="component component-variant/tone">...</div>

  • Prefer tokens over raw values when a decision is meant to repeat.

  • Prefer modifiers over creating new class names when expressing variants and tones.

  • If you need the same workaround twice, the system is missing a token, a utility, or a modifier.