SoliDS

SoliDS è il design system personale di soli92 — una fondamenta agnostica basata su design tokens e CSS variables, pronta all'uso con qualsiasi framework web e compatibile con shadcn/ui.

Contesto operativo per assistenti AI: AGENTS.md.

Storybook (documentazione interattiva + esempi UI) è pubblicato su GitHub Pages dopo ogni release su npm. Per la prima volta sul repo: Settings → Pages → Build and deployment: GitHub Actions.

---

Documentazione

Dove	Contenuto
Storybook (online)	Foundations (token, colori, spacing, tipografia, radius, temi), Getting Started, Design Principles, Roadmap, story UI (es. Button)
Questo repo, docs/*.mdx	Stesse pagine narrative servite da Storybook in locale (npm run storybook)
docs/shadcn-integration.md	Integrazione completa Tailwind + shadcn/ui + temi
docs/registry-model-1.md	Registry @solids, registry/r/, CLI shadcn add

In sviluppo, dopo npm install: npm run storybook avvia la documentazione su localhost (prima viene rigenerato il CSS Tailwind di anteprima con build:storybook-css).

Node e npm

• Node.js 22+ consigliato (file .nvmrc, workflow CI su GitHub Actions).
• .npmrc in repo: registry=https://registry.npmjs.org/ e tag=latest per evitare dist-tag globali non compatibili con il registry pubblico.

---

Cosa include

Layer	File	Descrizione
🎨 Tokens	dist/tokens/tokens.json	Palette completa, spacing, tipografia, shadow, radius, easing, z-index
🔤 Variables	dist/css/variables.css	CSS vars --sd-* per tema light (default)
🌗 Themes	dist/css/themes.css	Override dark, fantasy, cyberpunk, 90s-party + prefers-color-scheme: dark quando data-theme non è impostato
🔗 shadcn	dist/css/shadcn.css	Mapping variabili shadcn/ui → token SoliDS
🧱 Base	dist/css/base.css	Reset minimale, body, focus-visible, box-sizing
🛠️ Utilities	dist/css/utilities.css	Classi utility sd-* (flex, spacing, colori, badge, card…)
📦 Index	dist/css/index.css	Entrypoint unico che importa tutto nell'ordine corretto

---

Installazione

npm install @soli92/solids

---

Quick Start

Con Tailwind + shadcn/ui (Next.js, Vite…)

Consigliato: usa il preset Tailwind del pacchetto così tema, colori shadcn, font e shadow restano allineati ai token in un solo punto.

/* globals.css */
@import "@soli92/solids/css/index.css";

@tailwind base;
@tailwind components;
@tailwind utilities;

// tailwind.config.js
module.exports = {
  presets: [require("@soli92/solids/tailwind-preset")],
  content: ["./app/**/*.{ts,tsx}", "./components/**/*.{ts,tsx}"],
};

Serve anche tailwindcss-animate (dipendenza tipica di shadcn):

npm install tailwindcss-animate

Poi inizializza shadcn e aggiungi i componenti: tutto il kit con npx shadcn@latest add @solids/solids-ui oppure singoli item (@solids/solids-button, …). I componenti usano le variabili --background, --primary, ecc., già mappate da SoliDS. Esempio components.json: templates/components.json.example.

➡️ Guida completa: docs/shadcn-integration.md

Senza framework

<link rel="stylesheet" href="node_modules/@soli92/solids/dist/css/index.css" />

---

Esportazioni disponibili

import tokens from "@soli92/solids/tokens";           // tokens.json
import "@soli92/solids/css/index.css";                // tutto
import "@soli92/solids/css/variables.css";            // solo vars
import "@soli92/solids/css/themes.css";               // override temi + OS dark
import "@soli92/solids/css/shadcn.css";               // solo shadcn layer
import "@soli92/solids/css/base.css";                 // solo base
import "@soli92/solids/css/utilities.css";            // solo utilities

Preset Tailwind (shadcn): require("@soli92/solids/tailwind-preset") nel tailwind.config.

---

Token Reference

Colori (palette base)

gray · blue · green · amber · red · violet — ogni colore ha steps 50→900.

Token semantici (--sd-color-*)

Testo

• --sd-color-text-primary / secondary / tertiary / disabled / inverse / link / link-hover

Background

• --sd-color-bg-canvas / surface / elevated / overlay / hover / active / disabled

Border

• --sd-color-border-default / muted / strong / focus / disabled

Intent

• --sd-color-intent-success / warning / danger / info (+ -bg e -border per ognuno)

Componenti

• --sd-color-primary-default / hover / active / subtle / foreground
• --sd-color-secondary-* / muted-* / accent-* / destructive-*

Spacing (--sd-space-*)

xs sm md lg xl 2xl 3xl

Radius (--sd-radius-*)

none sm md lg xl full

Tipografia

• --sd-font-size-xs → 6xl
• --sd-font-weight-light → extrabold
• --sd-font-body / --sd-font-heading / --sd-font-mono

Shadow (--sd-shadow-*)

sm md lg xl

Motion

• --sd-duration-fast / normal / slow
• --sd-easing-ease-inout / ease-out / …

Z-index (--sd-z-*)

dropdown sticky overlay modal toast tooltip

---

Temi (light, dark, fantasy, cyberpunk, 90s-party)

Quattro temi globali tramite data-theme su <html>. Stessi token semantici (--sd-*), valori diversi per colore, font, raggio e ombre dove definito nei JSON tema.

<html data-theme="light">      <!-- esplicito (spesso coincide con default :root) -->
<html data-theme="dark">
<html data-theme="fantasy">    <!-- pergamena / serif / Cinzel negli heading -->
<html data-theme="cyberpunk">  <!-- neon; il preset Tailwind tratta anche questo come "dark" per le utility dark: -->
<html data-theme="90s-party"> <!-- rave / magenta-teal-lime; stesso trattamento dark: del preset Tailwind -->

Se data-theme non è impostato, prefers-color-scheme: dark applica i token dark (come data-theme="dark"). Fantasy, cyberpunk e 90s-party vanno scelti esplicitamente.

Con next-themes, usa attribute="data-theme" e, se vuoi tutti i temi nel selettore, estendi i temi oltre light/dark (vedi docs/shadcn-integration.md).

<ThemeProvider attribute="data-theme" defaultTheme="system" enableSystem>

---

Utility Classes (sd-*)

<!-- Layout -->
<div class="sd-flex sd-items-center sd-gap-md sd-p-lg">

<!-- Tipografia -->
<h1 class="sd-text-3xl sd-font-bold sd-text-primary">Titolo</h1>
<p class="sd-text-base sd-text-secondary">Sottotitolo</p>

<!-- Card -->
<div class="sd-card">...</div>

<!-- Badge -->
<span class="sd-badge sd-badge-success">Attivo</span>
<span class="sd-badge sd-badge-danger">Errore</span>

<!-- Container -->
<main class="sd-container">...</main>

---

Sviluppo

# Installa dipendenze
npm install

# Build (genera dist/)
npm run build

# Storybook (build token + Tailwind preview, poi dev server)
npm run storybook

# Release (semantic-release — solo da CI; aggiorna CHANGELOG, versione npm, GitHub release)
npm run release

# Registry shadcn (sync src → registry/solids + JSON in registry/r)
npm run registry:build

Per Storybook, il CSS Tailwind viene precompilato in .storybook/preview-tw.built.css (file ignorato da git) dallo script build:storybook-css.

Release, versioning e changelog

Su push a main, il workflow GitHub Release esegue semantic-release: analizza i commit (Conventional Commits, es. feat:, fix:), aggiorna CHANGELOG.md (plugin @semantic-release/changelog), bump di versione su npm, tag Git e GitHub Release con note generate. Non lanciare npm run release in locale salvo esigenze di debug: è pensato per CI (token NPM_TOKEN, GITHUB_TOKEN).

---

Framework UI (progetti personali + shadcn)

SoliDS resta agnostico: i componenti UI vivono nelle tue app (modello shadcn: codice in repo, non solo in node_modules). Il flusso consigliato:

1. Token e CSS — @soli92/solids (index.css + opzionale solo layer).
2. Tailwind — presets: [require("@soli92/solids/tailwind-preset")] + tailwindcss-animate.
3. shadcn/ui — npx shadcn@latest init e add per ogni blocco (Radix + CVA + le tue classi).
4. Tema — data-theme / next-themes come in docs/shadcn-integration.md.

In questo repository, Storybook include un esempio Button in stile shadcn in src/components/ui/button.tsx (solo sorgente di riferimento: non è incluso nell’artifact npm dist/; nei progetti veri aggiungi i componenti con la CLI shadcn).

Il registry shadcn per il modello 1 è in registry/ (sorgenti) e registry/r/ (JSON generati). Guida operativa: docs/registry-model-1.md.

---

Struttura

src/
├── tokens/
│   ├── base.json           # Palette, spacing, tipografia, shadow, easing, z-index
│   ├── semantic.json       # Token semantici (testo, bg, border, intent, componenti)
│   └── themes/
│       ├── light.json      # Override tema light
│       ├── dark.json       # Override tema dark
│       ├── fantasy.json     # Tema fantasy (palette, font, radius, shadow)
│       ├── cyberpunk.json   # Tema cyberpunk
│       └── 90s-party.json    # Tema 90s party (rave / MTV)
├── tailwind/
│   └── preset.cjs          # Preset Tailwind (shadcn + token SD)
├── components/ui/          # Esempio shadcn in Storybook
├── css/
│   ├── shadcn.css          # Compatibility layer shadcn/ui
│   ├── base.css            # Reset + global styles
│   └── utilities.css       # Classi utility sd-*
scripts/
├── build.mjs               # Build script → genera dist/
└── sync-registry.mjs       # Copia src → registry/solids (per shadcn build)
registry/
│   └── solids/             # Sorgenti registry (sync da src/)
registry.json               # Indice item shadcn (root repo)
registry/r/                 # JSON pubblicati (`npm run registry:build`)
docs/
├── index.mdx               # Intro (Storybook)
├── getting-started.mdx
├── principles.mdx
├── roadmap.mdx
├── foundations/            # Colori, spacing, typography, radius, themes, tokens
├── shadcn-integration.md   # Guida integrazione completa (markdown)
└── registry-model-1.md     # Modello shadcn in repo + @solids

---

Dove viene usato

Esempi di progetti che consumano @soli92/solids (preset Tailwind + CSS): portale soli-dome, app soli-agent. Lo Storybook pubblicato è linkato anche da soli-dome (categoria Design).

---

License

MIT © soli92