Adoption guide · v3.5.0

Start with one link. Understand the seams.

Inkwell is a framework-free CSS design system for product interfaces, dashboards, and editorial surfaces. Consumers do not install dependencies or run a build.

01

Install

3 required files

Copy inkwell.css, inkwell-tokens.css, and inkwell-components.css side by side. Link only the entry file; its imports resolve the other two.

<link rel="stylesheet" href="inkwell.css">

Optional interactions

Copy and load inkwell-interactions.js only if you use tabs, enhanced carousel controls, or declarative dialog triggers. Disclosures use native <details> and require no JavaScript.

<script src="inkwell-interactions.js"></script>
02

Architecture

source → entry → consumer
Inkwell distributable files and responsibilities
FileResponsibilityEdit?
inkwell-tokens.cssCanonical custom properties, light/dark values, mode machineryToken changes
inkwell-components.cssReset, type, components, layout, accessibilityComponent changes
inkwell.cssCanonical layered entryNo
tokens.cssDeprecated compatibility aliasNo; removed in 4.0
tokens.jsonGenerated external-tooling mirrorRegenerate, never hand-edit

Components load in @layer inkwell, so ordinary unlayered consumer CSS overrides them without specificity escalation. Tokens stay unlayered.

03

Theme and palette

auto · light · dark

Color tokens use light-dark(). Auto follows the operating system; set data-theme="light" or data-theme="dark" on <html> for a manual choice. Apply it before first paint when the preference is persisted.

<script>
  const saved = localStorage.getItem("inkwell-theme");
  if (saved === "light" || saved === "dark") {
    document.documentElement.dataset.theme = saved;
  }
</script>

For Clay, Sage, Burgundy, or Azure, load one override file after inkwell.css. A palette swaps brand-layer tokens and never repeats component CSS.

<link rel="stylesheet" href="inkwell.css">
<link rel="stylesheet" href="variants/azure.css">
04

Components

35 families

The component reference is the canonical adoption surface. It lists selectors, anatomy, modifiers, states, accessibility requirements, JavaScript responsibilities, version introduced, and copyable markup from one machine-readable manifest.

Open component referenceOpen visual showcase
Which components need JavaScript?

Tabs need selection and keyboard synchronization; enhanced carousel buttons need navigation state; declarative dialog triggers need showModal(), close handling, and focus restoration. Load the optional interaction file for those recipes. Everything else is CSS-only or relies on native HTML behavior.

05

Accessibility baseline

part of the API

Pages

One visible h1, one main landmark, a working skip link, logical headings, canonical metadata, and no page-level horizontal overflow.

Forms

Visible labels, useful names and autocomplete, aria-invalid="true", and aria-describedby pointing to error text.

Interaction

Keyboard parity, visible focus, reduced-motion support, no autoplay, and 44px controls on coarse-pointer devices.

06

Tailwind v4

alternate entry

Use inkwell-theme.css instead of inkwell.css. It imports the same canonical token and component sources, maps tokens into @theme, and keeps utilities above components in the cascade.

@import "tailwindcss";
@import "./inkwell-theme.css";

Use border-inkwell for the 1.5px signature border. The historical border-hair Tailwind alias still works through 3.x, but the CSS token --border-hair means a 1px divider.

Open the live Tailwind integration proof →
07

Agent adoption

one context file

Give an implementation agent agent-instructions.md. It contains the pinned 3.5.0 install URLs, component and token rules, interaction responsibilities, accessibility contracts, and the verification checklist. Repository-editing agents should also follow AGENTS.md.

Read agent-instructions.md before building UI.
Use the existing Inkwell tokens and components.
Verify light, dark, auto, keyboard, and 375px layout.