@soli92/solids

v1.14.1

Published

2 months ago

SoliDS – agnostic design system foundations (tokens + CSS) with shadcn/ui compatibility.

Downloads

255

0High
0Medium
0Low

soli92

design-system tokens css-variables shadcn shadcn-ui tailwind solids

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. SoliDS è indicizzato nella knowledge base Soli Prof (RAG); un push su main può notificare re-ingest tramite webhook lato Soli Prof (nessuna configurazione aggiuntiva in questo repository). Dettagli: AGENTS.md (Integrazione Soli Prof).

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, Accessibility and Motion), 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, steampunk, temi personaggio (ichigo, vegeta, zoro, captain-america, sasuke, inuyasha) + 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, body, scroll-padding / scroll-behavior (rispetto prefers-reduced-motion), focus-visible, text-rendering, box-sizing | | 🛠️ Utilities | dist/css/utilities.css | Classi sd-* (flex, spacing, colori, badge, card, .sd-min-touch-target, .sd-link, leading da token, .sd-transition-emphasized) | | 📦 Index | dist/css/index.css | Entrypoint unico che importa tutto nell'ordine corretto | | 🪪 Brand assets | dist/brand-assets/** | Set Soli (soli-icons, soli-category-icons) + raccolta workspace raw/normalized con index typed |

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" />

App consumer (Next.js, Vite, CRA, …)

Usa @soli92/solids@^1.12.0 su npm. Per i token --sd-font-* (Inter, DM Sans, JetBrains Mono e famiglie dei temi fantasy / cyberpunk / 90s-party / personaggio) carica in <head> le stesse Google Fonts definite in .storybook/preview-head.html (due link fonts.googleapis.com), così eviti fallback di sistema rispetto a Storybook.

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
import { IconHome, IconSearch } from "@soli92/solids/icons"; // icone SoliDS
import workspaceIconsIndex from "@soli92/solids/brand-assets/workspace-icons-normalized"; // index typed

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

Asset statici principali:

import logoSvg from "@soli92/solids/brand-assets/soli-category-icons/soli-icon-logo.svg";
import faviconPng from "@soli92/solids/brand-assets/soli-category-icons/soli-icon-favicon.png";
import appIconPng from "@soli92/solids/brand-assets/soli-category-icons/soli-icon-app-icon.png";

Componenti logo/loader:

import { LogoLoader, LogoLoaderOverlay } from "@/components/ui/logo-loader";

LogoLoader: default Soli 4:3 theme-aware + supporto src custom svg/png
LogoLoaderOverlay: overlay fullscreen theme-aware con message, blur, animazione e dimensione configurabili

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 (default: Inter / DM Sans / JetBrains Mono; temi nominati possono sovrascrivere)
--sd-font-leading-none … loose (interlinea da token)

Shadow (`--sd-shadow-*`)

sm md lg xl

Layout e motion (UX / a11y)

--sd-layout-touch-target-min — 44px, target comodi (WCAG 2.5.8 / HIG; vedi doc Accessibility and Motion)
--sd-duration-fast / normal / slow / emphasized (350ms, transizioni più evidenti)
--sd-easing-standard (curva MD3) / emphasized-decelerate / emphasized-accelerate / ease-inout / ease-out / …

Documentazione accessibilità

In Storybook e in docs/foundations/accessibility-and-motion.mdx: riferimenti a WCAG 2.2, Material Design 3 (motion, typography), Apple HIG, e uso delle utility sopra.

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

dropdown sticky overlay modal toast tooltip

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

Temi globali tramite data-theme su <html>. Stessi token semantici (--sd-*), valori diversi per colore, font, raggio e ombre. I default light / dark sono orientati a superfici tonali, raggi più generosi e ombre a livelli in stile Material Design 3, mantenendo il blu primary tipico di shadcn.

<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 -->
<html data-theme="steampunk"> <!-- ottone/rame, serif vittoriano; dark: come cyberpunk -->
<html data-theme="ichigo"> <!-- ispirazione palette Bleach; dark: -->
<html data-theme="vegeta"> <!-- ispirazione Dragon Ball; dark: -->
<html data-theme="zoro"> <!-- ispirazione One Piece; dark: -->
<html data-theme="captain-america"> <!-- blu notte + rosso; dark: -->
<html data-theme="sasuke"> <!-- ispirazione Naruto; dark: -->
<html data-theme="inuyasha"> <!-- ispirazione Inuyasha; dark: -->

Se data-theme non è impostato, prefers-color-scheme: dark applica i token dark (come data-theme="dark"). Fantasy, cyberpunk, 90s-party, steampunk e i temi personaggio 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

# Test: build + verifiche token (`scripts/tokens-sanity.mjs`) + Storybook static
npm test
# Solo verifiche token (dopo build manuale)
npm run test:tokens

# 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:

Token e CSS — @soli92/solids (index.css + opzionale solo layer).
Tailwind — presets: [require("@soli92/solids/tailwind-preset")] + tailwindcss-animate.
shadcn/ui — npx shadcn@latest init e add per ogni blocco (Radix + CVA + le tue classi).
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, dark, fantasy, cyberpunk, 90s-party, steampunk + temi personaggio (*.json)
├── 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/
├── tokens-sanity.mjs       # Verifiche post-build su tokens.json + variables.css (`npm run test:tokens`)
└── 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, accessibility-and-motion
├── 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).