@valiify/dashboard-ui

A Tailwind CSS component library for Valiify Dashboard applications.

40 verified components extracted from Figma. CSS-only, framework-agnostic, zero JavaScript dependencies.

⚠️ Important: Read This First

This package requires a build tool. Installing npm install @valiify/dashboard-ui tailwindcss is not enough. You also need:

• Vite: @tailwindcss/vite
• webpack: @tailwindcss/webpack
• PostCSS/Next.js: @tailwindcss/postcss
• No bundler: @tailwindcss/cli

Without one of these packages, nothing will work. No errors, no styles. See Installation below.

Quick Start (Recommended)

The fastest way to get started is to use our verified example:

# Copy the Vite starter
npx degit BubbaCoop/Valiify-dashboard-ui/examples/vite-starter my-app
cd my-app

# Install and run
npm install
npm run dev

Open http://localhost:5173 - if you see styled components with working icons, you're done.

Or: See the complete installation guide for manual setup with any build tool.

Entry points

| Import | Use it when | | --- | --- | | @valiify/dashboard-ui/styles.css | dropping the library into a host app that already has a reset — no Preflight, no html rule, unlayered, closed vd: utility set | | @valiify/dashboard-ui | a standalone page where our Preflight is welcome | | @valiify/dashboard-ui/source | your Tailwind compiles our @theme, giving every token utility | | @valiify/dashboard-ui/reset.css | optional — pair it with ./styles.css when that bundle is the ONLY stylesheet on the page |

Component classes are namespaced: .vd-btn, .vd-card-title, .vd-input-field. The generated list ships as @valiify/dashboard-ui/manifest.

/* a host app — the @import must come FIRST, CSS discards a later one */
@import "@valiify/dashboard-ui/styles.css";
@tailwind base;
@tailwind components;
@tailwind utilities;

Do you need ./reset.css?

./styles.css ships no Preflight, so it cannot fight your reset. The flip side is that a page with no other stylesheet falls back to the browser's defaults, and three of those break the library's geometry: elements are content-box, so every padded component renders wider and taller than designed (the small input measures 38px against a designed 25); <p> and <h2> carry a 1em margin inside Alert, Toast, Modal and Tooltip; <button> carries a 2px UA border. Text also falls back to the UA serif, because the bundle defines --font-sans but has no Preflight to bind it.

/* a standalone page — the reset FIRST, then the bundle */
@import "@valiify/dashboard-ui/reset.css";
@import "@valiify/dashboard-ui/styles.css";

Skip it inside an app that already has a reset. Its first eight rules would be redundant there, and its ninth sets html { color; background-color } — a page default your app owns. Nothing imports this file for you.

It is about twenty lines and deliberately not a Preflight: no lists, tables, images, fieldsets, form-control appearance or placeholder colour. Every rule is there because a measured value was wrong without it, and both directions are gated in CI (npm run verify:reset) — it must override nothing the bundle declares, and it must still render the documented markup exactly as @valiify/dashboard-ui (the Preflight-carrying entry) does.

./styles.css does not render "identically" to ./source. Its contract is narrower and checkable, in two clauses:

1. What it defends against. The bundle is unlayered. Load it after your reset and its component rules beat any host rule of lower specificity, wherever that rule sits in source order — Tailwind 3 preflight, daisyUI's base, a :global(button) reset in a Svelte component. (0.2.0 did not hold this: its rules sat in @layer components and lost to every unlayered host rule. The fingerprint was a control whose focus ring survived while its border, fill and padding did not.)
2. What it cannot defend against. A host rule of higher specificity still wins. A Svelte scoped button { border: 0 } compiles to button.svelte-hash (0,1,1) and beats our single-class rules (0,1,0). A host that wraps its own CSS in a cascade layer changes the arithmetic too. Scope element resets by class, or exclude library controls: button:not([class*="vd-"]) { border: 0 }.

Both clauses are measured in examples/daisyui-starter (Tailwind 3 + daisyUI 4, three load paths) and examples/sveltekit-starter (Svelte scoped styles, including clause 2 asserted as a loss) — npm run check in each.

Installation

Step 1: Install Packages

Choose based on your build tool:

# Vite (recommended)
npm install @valiify/dashboard-ui tailwindcss @tailwindcss/vite

# webpack
npm install @valiify/dashboard-ui tailwindcss @tailwindcss/webpack

# PostCSS / Next.js
npm install @valiify/dashboard-ui tailwindcss @tailwindcss/postcss

# Tailwind CLI (no bundler)
npm install @valiify/dashboard-ui tailwindcss @tailwindcss/cli

⚠️ You need THREE packages, not two. tailwindcss alone doesn't process CSS in v4. Missing the integration package (the third one above) causes silent failure.

Step 2: Configure Your Build Tool

Vite - create/update vite.config.js:

import { defineConfig } from "vite";
import tailwindcss from "@tailwindcss/vite";

export default defineConfig({
  plugins: [tailwindcss()],
});

PostCSS - create/update postcss.config.js:

export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

webpack - add to your config:

import tailwindcss from "@tailwindcss/webpack";

export default {
  plugins: [tailwindcss()],
};

Tailwind CLI - no config needed, build with:

npx @tailwindcss/cli -i src/styles.css -o dist/styles.css --watch

Step 3: Create Your Stylesheet

Create a CSS file (e.g., src/styles.css):

/* Optional: Load fonts */
@import url("https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&family=JetBrains+Mono:wght@400;500&display=swap");

/* Required: Tailwind first */
@import "tailwindcss";

/* Required: Valiify UI second */
@import "@valiify/dashboard-ui/source";

⚠️ CRITICAL: Import from CSS, never from JavaScript. See Common Mistakes.

Step 4: Import Your Stylesheet

In your JavaScript entry point:

// main.js
import "./styles.css"; // ✅ Import YOUR stylesheet, not the library

Step 5: Load Icons

Add to your JavaScript:

import spriteUrl from "@valiify/dashboard-ui/icons/sprite.svg?url";

fetch(spriteUrl)
  .then((r) => r.text())
  .then((svg) => {
    const host = document.createElement("div");
    host.style.display = "none";
    host.innerHTML = svg;
    document.body.prepend(host);
  });

Step 6: Use Components

<button class="vd-btn vd-btn-primary">Click me</button>

<div class="vd-input-container">
  <div class="vd-input-field">
    <input type="text" class="vd-input" placeholder="Enter text..." />
  </div>
</div>

<span class="vd-chip vd-chip-success">
  <span class="vd-chip-dot"></span>
  <span>Approved</span>
</span>

Documentation

Getting Started

• GETTING_STARTED.md - Complete installation guide for all build tools
• COMPONENTS.md - Full markup examples for every component
• TROUBLESHOOTING.md - Debug guide for common issues

Examples

• examples/vite-starter/ - Working Vite setup (recommended)
• examples/postcss-starter/ - PostCSS CLI setup
• examples/basic/ - Standalone HTML (prebuilt CSS)

Reference

• CLAUDE.md - Technical reference: every component's structure, states, and Figma differences
• CHANGELOG.md - Version history and breaking changes

Available Components

Form Controls

Button • IconButton • TextButton • Input • Textarea • Checkbox • RadioSelect • Switch • DropdownField • SensitiveData

Data Display

Avatar • Chip • Badge • Dot • Tag • Pill • DataRow • Divider • Icon • Skeleton

Navigation

NavigationRail • Tabs • SegmentSelector • FilterSegment • Breadcrumbs • Pagination • MenuItem • DropdownMenu • Link

Feedback

Alert • Toast • Modal • Tooltip • LoadingIndicator • LoadingInline • ProgressBar • Stepper

Review Components

FieldVerification • SectionMarker

Note: Card is placeholder scaffolding, not a real component. Don't use it.

See COMPONENTS.md for complete markup of every component.

Components That Need JavaScript

These components ship zero JavaScript - you must implement behavior:

• DropdownField / DropdownMenu - Toggle aria-expanded, show/hide panel, close on outside click
• Tabs - Toggle aria-selected, show/hide panels
• Modal - Open/close handlers (or use native <dialog> - recommended)
• Tooltip - Show/hide, positioning
• NavigationRail - Group disclosure (toggle aria-expanded)

See GETTING_STARTED.md for minimal implementation examples.

Common Issues

Styles don't apply at all

Cause: Missing integration package or wrong import.

Fix:

1. Install @tailwindcss/vite (or postcss/webpack/cli)
2. Register it in your config
3. Import from CSS, not JavaScript

See TROUBLESHOOTING.md.

Icons don't show

Cause: Sprite didn't load.

Fix: Add sprite loading code (Step 5 above). See TROUBLESHOOTING.md.

Token utilities don't work

Cause: Using prebuilt / entry instead of /source.

Fix: Change @import "@valiify/dashboard-ui" to @import "@valiify/dashboard-ui/source".

Component looks broken

Cause: Missing wrapper elements.

Fix: Check COMPONENTS.md for required markup structure.

Dropdown/Tabs/Modal don't work

Cause: These components need JavaScript.

Fix: See Components That Need JavaScript.

Two Entry Points

/* /source - for apps with Tailwind build (recommended) */
@import "tailwindcss";
@import "@valiify/dashboard-ui/source";

/* / (prebuilt) - for standalone HTML, no Tailwind build */
<link rel="stylesheet" href="node_modules/@valiify/dashboard-ui/dist/index.css">

Use /source for:

• Any app with a bundler (Vite, webpack, Next.js, etc.)
• When you want token utilities (bg-approved, rounded-pill, type-label-l)
• When your own @theme should survive

Use / (prebuilt) only for:

• Standalone HTML pages with no build process
• Email previews
• Static prototypes

See GETTING_STARTED.md for details.

Design System

Built on the Valiify Figma design system (Commercial-Designs, FdcEV83HPv44bzLPAQU1hR).

40 colors • 5 radii • 3 border widths • 37 text styles • 4 shadows • 6 label utilities

All tokens are extracted from Figma, not hand-written. They live in a Tailwind @theme block, so each one generates utilities:

/* Token → Utilities */
--color-approved     → bg-approved, text-approved, border-approved
--radius-control     → rounded-control
--text-body-1        → text-body-1 (size + line-height + weight + tracking)

Browse the full set in Storybook under Foundations → Design Tokens.

Typography: Inter (UI) + JetBrains Mono (data). Not bundled - see Fonts.

Colors: OKLch notation for perceptual uniformity.

Token names are public API. Renaming or removing a token is a breaking change. Changing a token's value is not.

Fonts

Fonts are not bundled. Either self-host or import ours first:

@import "@valiify/dashboard-ui/fonts"; /* must be first line */
@import "tailwindcss";
@import "@valiify/dashboard-ui/source";

Self-hosting is better for performance and privacy.

Development

Install

git clone https://github.com/BubbaCoop/Valiify-dashboard-ui.git
cd Valiify-dashboard-ui
npm install

Build

npm run build        # Build library
npm run dev          # Build + watch
npm run build:theme  # Regenerate tokens from Figma JSON

Storybook

npm run storybook    # Dev server at http://localhost:6006
npm run build-storybook

Verify

npm run audit                    # Coverage check
npm run verify:component Avatar  # Static source check
npm run verify:layers            # Cascade-layer contract
npm run verify:visual            # Rendered styles vs Figma
npm run verify:a11y              # Accessibility scan
npm run typecheck                # TypeScript

All verification runs in CI: .github/workflows/ci.yml

Add a Component

npm run new:component Badge  # Scaffold CSS, story, types

See docs/component-process.md for the full process.

Architecture

• CSS-only - Zero JavaScript dependencies
• Tailwind v4 @theme - Tokens generate utilities automatically
• No Tailwind plugin - No tailwind.config.js to register
• Single light theme - V1 ships one theme; no dark mode yet
• Framework-agnostic - Works with React, Vue, Svelte, vanilla HTML

Status

Current: Phase 3 complete - 40 components built and verified
Next: Accessibility remediation, then publish to NPM

Links

• Repository: https://github.com/BubbaCoop/Valiify-dashboard-ui
• Figma: Commercial-Designs (FdcEV83HPv44bzLPAQU1hR)
• NPM: @valiify/dashboard-ui
• Storybook: Not yet deployed

Contributing

Not accepting external contributions yet. This is a pre-release package under active development.

License

MIT © Valiify

Still Having Issues?

1. Check the examples - examples/vite-starter/ is a verified working setup
2. Read GETTING_STARTED.md - Covers all build tools
3. Read TROUBLESHOOTING.md - Debug guide
4. Read COMPONENTS.md - Complete markup reference
5. Search issues - https://github.com/BubbaCoop/Valiify-dashboard-ui/issues
6. Open an issue - Include your setup, config files, and what you've tried