Getting Started — Coconut Design System

Overview

What is Coconut Design System?

Coconut Design System is a vanilla CSS + JavaScript design system purpose-built for admin dashboards deployed on Cloudflare Pages. It requires no framework dependency — no React, no Vue, no Svelte. Just clean, semantic HTML styled with CSS custom properties and enhanced with lightweight vanilla JS.

The system ships with a comprehensive set of design tokens, pre-built components, responsive layout primitives, and full dark mode support out of the box.

text_fields

Inter

Primary typeface (300-700)

code

JetBrains Mono

Code, IPs, versions

emoji_symbols

Material Symbols

Outlined, variable weight

info Zero dependencies. Coconut Design System has no npm runtime dependencies. The only external resources are Google Fonts for Inter, JetBrains Mono, and Material Symbols Outlined.

Installation

Option 1 — Clone the repository

# Clone the design system $ git clone https://github.com/Coconut-Services/coconut-design-system.git $ cd coconut-design-system # Install dev dependencies (optional — for docs site only) $ npm install # Start local development server $ npm run dev

Option 2 — Copy the CSS files directly

Copy the three core files into your project and reference them in your HTML. No build step required.

# Copy these files into your project $ cp src/styles/design-tokens.css your-project/styles/ $ cp src/styles/components.css your-project/styles/ $ cp src/js/main.js your-project/js/

CDN Links for Fonts & Icons

Add these to the <head> of every page. The preconnect hints ensure fonts load as fast as possible.

<!-- Preconnect for performance -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>

<!-- Inter + JetBrains Mono -->
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700
  &family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">

<!-- Material Symbols Outlined -->
<link href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:
  opsz,wght,FILL,GRAD@24,400..600,0,0&display=swap" rel="stylesheet">

Project Structure

File tree — core files highlighted

coconut-design-system/
|
|-- src/
|   |-- styles/
|   |   |-- design-tokens.css   # CSS custom properties (colors, spacing, shadows, radii)
|   |   |-- components.css      # All UI components (buttons, badges, cards, tables...)
|   |   |-- docs.css              # Documentation site styles (not needed in production)
|   |
|   |-- js/
|   |   |-- main.js              # Theme toggle, accordion, copy-to-clipboard, sidebar
|   |
|   |-- pages/                    # Documentation pages (this site)
|       |-- getting-started.html
|       |-- tokens.html
|       |-- components.html
|       |-- layout.html
|       |-- patterns.html
|       |-- icons.html
|       |-- ...
|
|-- index.html                    # Landing page
|-- package.json

warning Production usage: You only need design-tokens.css, components.css, and main.js. The docs.css file is only used for the documentation site itself.

Quick Start

Minimal dashboard page — topbar + sidebar + main content

Copy this template to create a new dashboard page. It includes the complete shell structure with topbar, sidebar navigation, and a content area ready for your components.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>My Dashboard</title>

    <!-- Fonts -->
    <link rel="preconnect" href="https://fonts.googleapis.com">
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700
      &family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
    <link href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:
      opsz,wght,FILL,GRAD@24,400..600,0,0&display=swap" rel="stylesheet">

    <!-- Coconut Design System -->
    <link rel="stylesheet" href="styles/design-tokens.css">
    <link rel="stylesheet" href="styles/components.css">
</head>
<body>
    <!-- Dark mode: instant flash-prevention -->
    <script>
      if (localStorage.getItem("ds-theme") === "dark" ||
          (!localStorage.getItem("ds-theme") &&
           matchMedia("(prefers-color-scheme:dark)").matches)) {
        document.body.classList.add("dark");
      }
    </script>

    <!-- Topbar -->
    <header class="topbar">
        <div class="topbar-left">
            <div class="topbar-logo-icon">
                <span class="material-symbols-outlined">palette</span>
            </div>
            <div class="topbar-divider"></div>
            <span class="topbar-title">My Dashboard</span>
            <span class="topbar-version">v1.0.0</span>
        </div>
        <div class="topbar-right">
            <button class="theme-toggle" onclick="toggleTheme()">
                <span class="material-symbols-outlined">dark_mode</span>
            </button>
        </div>
    </header>

    <!-- Sidebar -->
    <nav class="sidebar">
        <div class="sidebar-section">
            <div class="sidebar-label">MENU</div>
            <a class="sidebar-link active">
                <span class="sidebar-icon" style="background:#744F28;">
                    <span class="material-symbols-outlined">home</span>
                </span>
                Home
            </a>
            <a class="sidebar-link">
                <span class="sidebar-icon" style="background:#2e7d32;">
                    <span class="material-symbols-outlined">monitoring</span>
                </span>
                Monitoring
            </a>
        </div>
    </nav>

    <!-- Main Content -->
    <main class="main-content">
        <h1 class="page-title">Dashboard</h1>
        <p class="page-desc">Welcome to your dashboard.</p>

        <div class="grid grid-3">
            <div class="card">
                <div class="card-header">
                    <span class="card-label">METRIC</span>
                    <span class="badge badge-green">
                        <span class="badge-dot"></span>Active
                    </span>
                </div>
                <div class="card-title">Server Uptime</div>
                <div class="card-sub">99.97%</div>
            </div>
            <!-- more cards... -->
        </div>
    </main>

    <script type="module" src="js/main.js"></script>
</body>
</html>

check_circle That's it! Open this HTML file in a browser and you have a fully styled dashboard with topbar, sidebar, responsive layout, and dark mode toggle. No build step needed.

Theming

Customizing with CSS Custom Properties

Every visual property in Coconut is defined as a CSS custom property (variable) on :root. To customize the look and feel, simply override these tokens in your own stylesheet loaded after the design system.

/* your-theme.css — loaded after design-tokens.css */

:root {
    /* Override the primary accent color */
    --accent: #5C3D1E;
    --accent-dark: #6d28d9;
    --accent-container: #ede9fe;
    --on-accent-container: #3b0764;

    /* Override border radius for a sharper look */
    --radius: 8px;
    --radius-lg: 12px;

    /* Override sidebar width */
    --sidebar-w: 220px;
}

/* Override dark mode tokens */
body.dark {
    --bg: #0f0f23;
    --white: #1a1a2e;
    --accent: #C4956A;
}

Key tokens you can override

Token	Default	Description
`--accent`	#744F28	Primary brand / action color
`--bg`	#f3f4f6	Page background
`--white`	#ffffff	Card / surface background
`--border`	var(--gray-200)	All borders and dividers
`--text`	var(--gray-900)	Primary text color
`--radius`	12px	Default border radius
`--radius-lg`	16px	Large radius (cards, modals)
`--sidebar-w`	240px	Sidebar width
`--topbar-h`	56px	Topbar height
`--mono`	JetBrains Mono	Monospace font family

info Scoped theming: You can scope token overrides to any container (e.g. .my-panel { --accent: #e88400; }) to create isolated themed sections within the same page.

Platform Support

Tested on all major operating systems

Platform	Tested On	Status
desktop_windows Windows	Windows 10 / 11 — Chrome, Edge, Firefox	Supported
laptop_mac macOS	macOS 13+ — Safari, Chrome, Firefox	Supported
terminal Ubuntu / Linux	Ubuntu 22.04+ — Chrome, Firefox	Supported

Design Principles

Every decision in Coconut Design System is guided by four core principles.

tune

Consistency

Shared design tokens ensure every page looks and feels the same. Colors, spacing, typography, and shadows are defined once and reused everywhere through CSS custom properties.

accessibility_new

Accessibility

All components meet WCAG 2.1 AA contrast ratios. Focus states are visible, interactive elements have proper ARIA roles, and the system respects prefers-reduced-motion.

bolt

Performance

No framework overhead. Pure CSS animations with will-change hints. Minimal JavaScript. The entire system ships under 25 KB (gzipped). Optimized for Cloudflare Pages edge delivery.

dark_mode

Dark Mode Native

Dark mode is not an afterthought. Every component is designed for both themes simultaneously. Toggle with a single class on body.dark and all tokens adapt automatically. Respects system preference via prefers-color-scheme.

What's Next?

palette

Design Tokens

Colors, typography, spacing

toggle_on

Components

Buttons, badges, cards, forms

dashboard

Layout

Grid, topbar, sidebar, responsive