Struct UI

Framework‑agnostic Tailwind CSS UI component library (no JavaScript).

Struct UI ships a pre‑built CSS file (struct-ui.css / struct-ui.min.css) with a curated set of components and layout primitives that work in any stack: plain HTML, Laravel, Rails, React, Vue, etc. You bring your own HTML and JS; Struct UI provides the design system and utility classes.

Features

• Framework‑agnostic: Works anywhere you can include a CSS file.
• No JavaScript: Just CSS and Tailwind utilities; you control interactions.
• Component library: Buttons, inputs, tables, navbars, modals, toasts, accordions, tabs, and more.
• Utility‑first: Built on Tailwind CSS 4 with extra design tokens and utilities.
• Production‑ready: Minified CSS build (struct-ui.min.css) and docs built with VitePress.

Installation

You can use Struct UI in two main ways:

1. As a CSS library (recommended for most users)
2. As a Tailwind plugin/source (for deeper customization)

1. Install via npm (CSS library)

npm install @structdk/ui
# or
pnpm add @structdk/ui

After installation, the prebuilt CSS files will be available in the package’s dist folder:

• dist/struct-ui.css
• dist/struct-ui.min.css

Include one of these in your app:

<!-- Example: include from node_modules in a bundler setup -->
<link
  rel="stylesheet"
  href="/node_modules/@structdk/ui/dist/struct-ui.min.css"
/>

In most bundler setups (Vite, Webpack, Laravel Mix, etc.) you will typically import the CSS in your main entry:

// main.js / app.js / main.tsx, etc.
import '@structdk/ui/dist/struct-ui.css';

2. Use as Tailwind source (advanced / design systems)

If you want to integrate Struct UI into your own Tailwind build and tree‑shake, you can import its CSS into your Tailwind entry file.

Your Tailwind input (for example src/css/tailwind.css) already looks like this in this repo, but for consumers the idea is:

@import '@structdk/ui/dist/struct-ui.css';

Note: Tailwind 4 uses the new @tailwindcss/cli. Make sure you’re on Tailwind v4+ if you want to deeply integrate or extend classes. For most users, just including the built CSS is enough.

Basic Usage

Once the CSS is loaded, you can use Struct UI components by combining:

• Component classes (e.g. btn, card, input, badge, etc.)
• Variant classes (e.g. btn-primary, btn-outline-secondary, badge-success, etc.)
• Tailwind utilities for layout (e.g. flex, gap-4, space-y-4, w-full)

Example: Buttons

<div class="flex flex-col gap-4">
  <!-- Solid -->
  <button class="btn btn-default">Default</button>
  <button class="btn btn-primary">Primary</button>
  <button class="btn btn-secondary">Secondary</button>
  <button class="btn btn-success">Success</button>
  <button class="btn btn-warning">Warning</button>
  <button class="btn btn-danger">Danger</button>

  <!-- Soft -->
  <button class="btn btn-soft-primary">Soft primary</button>
  <button class="btn btn-soft-secondary">Soft secondary</button>

  <!-- Outline -->
  <button class="btn btn-outline-default">Outline default</button>
  <button class="btn btn-outline-secondary">Outline secondary</button>

  <!-- Text -->
  <button class="btn btn-text-default">Text default</button>
  <button class="btn btn-text-secondary">Text secondary</button>

  <!-- Sizes & shapes -->
  <button class="btn btn-sm btn-default">Small</button>
  <button class="btn btn-default">Default</button>
  <button class="btn btn-lg btn-primary">Large</button>
  <button class="btn btn-pill btn-primary">Pill</button>
  <button class="btn btn-rounded btn-default">Rounded</button>
  <button class="btn btn-square btn-default">Square</button>
</div>

Example: Icon buttons

<button class="btn btn-primary btn-icon" aria-label="Add">
  <!-- Any icon: Heroicons, Lucide, etc. -->
  <svg
    xmlns="http://www.w3.org/2000/svg"
    viewBox="0 0 24 24"
    fill="none"
    stroke="currentColor"
    stroke-width="2"
    class="w-4 h-4"
  >
    <path
      stroke-linecap="round"
      stroke-linejoin="round"
      d="M12 4.5v15m7.5-7.5h-15"
    />
  </svg>
</button>

Classes like btn, btn-primary, btn-soft-*, btn-outline-*, btn-text-*, btn-sm, btn-lg, btn-pill, btn-icon, etc. are all defined by Struct UI.

Components Overview

Struct UI ships styles and examples for (non‑exhaustive list):

• Form & input components
  • button, input, textarea, checkbox, radio, toggle, select, file-upload, datepicker
• Layout & navigation
  • navbar, sidebar, tabs, pagination, accordion, collapse
• Feedback & state
  • badge, toast, empty-state, progress, countdown
• Data display
  • card, table, timeline, avatar, chat-bubble, carousel
• Overlays
  • modal, dropdown

For each of these there is:

• A CSS file under src/css/components/…
• An HTML usage example under src/components/…

If you’re consuming the package from npm, you don’t need the source files, but the structure tells you which classes exist and how they are intended to be combined.

Using in Different Environments

Plain HTML

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Struct UI Demo</title>
    <link
      rel="stylesheet"
      href="/node_modules/@structdk/ui/dist/struct-ui.min.css"
    />
  </head>
  <body class="bg-gray-50 text-gray-900">
    <main class="p-6 space-y-6">
      <h1 class="text-2xl font-semibold">Struct UI demo</h1>
      <button class="btn btn-primary">Click me</button>
    </main>
  </body>
</html>

React / Vue / Svelte

Import the CSS once at the root of your app:

// main.jsx / main.tsx
import '@structdk/ui/dist/struct-ui.css';

Then just use the classes in your components:

export function PrimaryButton({ children }) {
  return <button className='btn btn-primary'>{children}</button>;
}

Laravel / Blade / Rails / etc.

• Make the CSS available (copy from node_modules/@structdk/ui/dist into your public assets, or let your bundler handle it).
• Use the same classes in your Blade / ERB templates:

<button class="btn btn-primary">
    Save
</button>

Working on this repo (contributors)

If you’re developing Struct UI itself (not just using it as a dependency), the main scripts are:

• npm run dev: Run Tailwind in watch mode and output to dist/struct-ui.css.
• npm run build:css: Build normal and minified CSS (struct-ui.css and struct-ui.min.css) and copy to the docs public folder.
• npm run docs:dev: Build CSS and run the VitePress docs locally.
• npm run docs:build: Build the VitePress docs.
• npm run build: Build CSS + docs (used before publishing).

Local development

git clone [email protected]:structdk/struct.ui.git
cd struct.ui
npm install

# Develop CSS in watch mode
npm run dev

# Or run docs locally
npm run docs:dev

The main entry points are:

• src/css/tailwind.css – Tailwind entry that compiles into dist/struct-ui.css
• src/css/components/* – Component‑level styles
• src/components/*.html – Example usage of all components
• docs – VitePress documentation site

Browser support

Struct UI is built on modern CSS and Tailwind 4 utilities. It is primarily tested in:

• Latest Chrome
• Latest Firefox
• Latest Safari
• Latest Edge

Legacy browsers (e.g. IE11) are not supported.

License

Struct UI is released under the MIT License. See LICENSE for details.