ui-architecture

Files (1)

• SKILL.md

SKILL.md (first lines)

# UI Architecture & Design Guidelines

VaultLock uses a centralized UI architecture based on Tailwind CSS v4, a strict Button System, and a shadcn-inspired structure.

## UI System & Brand Identity

- **Primary Color**: Jade / Mint Green (`#00a86b`).
- **Theme**: Dark AND Light mode required. Use `class="dark"` on `<html>` for dark mode (Tailwind v4 class strategy). The primary brand color `#00a86b` must remain consistent in both themes.
- **Logos**: When displaying third-party services (e.g., Netflix, Spotify), use `https://unavatar.io/[domain]` dynamically. Do NOT hardcode a list of company logos.

## Typography (MANDATORY)

- **Display / Headings**: Use **Geist Sans Bold** (`font-sans font-bold`) for titles and hero text. Geist Pixel is deferred — do NOT use `font-pixel` until it is properly loaded.
- **Body / UI text**: Use **Geist** (Sans) — clean, modern, readable. Apply via `font-sans`.
- **Code / Data**: Use **Geist Mono** — for passwords, tokens, hashes. Apply via `font-mono`.
- **Casing (Mayúsculas y Minúsculas)**: NUNCA uses ALL CAPS (todo mayúsculas) ni all lowercase. Todo el texto de la UI, botones y títulos debe usar **Sentence case** o **Title Case**.
- **PROHIBITION**: Never use default browser fonts or any other font family. Never use hardcoded hex colors `[#hex]` in className — always use CSS token classes (`text-primary`, `text-on-surface`, `bg-surface-low`, etc.).

## Tailwind v4 Rules

VaultLock uses **Tailwind CSS v4**, which introduces several breaking changes compared to v3:

- **Syntax Changes (CRITICAL)**: The `!important` modifier now goes at the **end** of the class name, not the beginning.
  - ❌ `!p-0` or `!bg-red-500`
  - ✅ `p-0!` or `bg-red-500!`
- **Configuration (`globals.css`)**: All design tokens are defined in `globals.css` using the `@theme` directive. There is no `tailwind.config.js`. Use `@layer components { ... }` or `@utility` directly in `globals.css` for reusable patterns.
- **Class Usage Strictness**: Never use arbitrary value hex codes in class names (e.g., `bg-[#09090b]`). Always use the semantic tokens defined in our design system (`bg-surface-base`, `text-primary`).
- **Known Errors & Troubleshooting**:
  - "The class `!p-0` can be written as `p-0!`" -> Always use the trailing `!` modifier in v4.
  - Duplicate text rendering with `@font-face` on unavailable CDNs -> Defer `Geist Pixel` until a local/reliable source is added; fallback to `font-sans font-bold`.
  - Broken SVG logos from external sources (unavatar.io) -> Use the `<ServiceAvatar>` client component which handles `onError` gracefully.

## Component Architecture & cn() Conventions (shadcn-inspired)

> **Important**: VaultLock does NOT use the shadcn/ui library. This skill defines the **architectural pattern inspired by shadcn** — folder structure and class-merging conventions only.

- **`@/components/ui/`**: Low-level, reusable primitive components (e.g. `Button.tsx`, `Badge.tsx`, `Input.tsx`). No business logic here.
- **`@/components/`**: Domain/feature components that compose `ui/` primitives (e.g. `VaultCard.tsx`, `Sidebar.tsx`, `BottomSheet.tsx`).
- **`@/lib/utils.ts`**: The ONLY place where `cn()` is defined. Never redefine it elsewhere. Install `clsx` and `tailwind-merge` via pnpm.

```ts
// @/lib/utils.ts
import { clsx, type ClassValue } from "clsx";
import { twMerge } from "tailwind-merge";

export function cn(...inputs: ClassValue[]): string {
  return twMerge(clsx(inputs));
}
```
**NEVER** concatenate classes with template literals or `.join()`. Use `cn()` instead. Every primitive in `components/ui/` must accept and forward a `className` prop.

## Modals & Layout Patterns (MANDATORY UX)

- **Modal Containers**: Use `<Modal>` as the base. Apply `rounded-[24px]` and `bg-surface-low` for elevation inside the modal content definition.
- **Modal Headers**: Always align icons and titles horizontally:
  `<div className="flex items-center gap-4 mb-4"><div className="w-12 h-12 rounded-full..."><Icon/></div><h2>Title</h2></div>`
- **Action Buttons (Responsive)**: Always use the hybrid responsive pattern for primary/secondary actions in modals or forms.
  - Desktop: Right-aligned (`justify-end`).
  - Mobile: Full-width stacked (`flex-col-reverse` so Cancel is below Primary).
  - Classes: `<div className="flex flex-col-reverse sm:flex-row sm:items-center sm:justify-end gap-3 pt-2"><Button className="w-full sm:w-auto">Cancel</Button>...</div>`

## Button System

Esta guía define las directrices visuales, jerárquicas y funcionales para los botones dentro de VaultLock.

### 1. Jerarquía y Semántica

| Variante | Acciones Comunes | Descripción Visual | Regla de Uso |
| :--- | :--- | :--- | :--- |
| **Primary** (`primary`) | Crear, Guardar, Aceptar, Continuar | Fondo Jade (`--color-primary`), texto negro, glow verde suave al hover. | **Máximo 1 por vista o modal principal.** Atrae la atención hacia la acción deseada. |
| **Secondary** (`secondary`) | Editar, Ver detalles, Descargar, Exportar | Fondo transparente, borde sutil (`rgba(255,255,255,0.1)`). | Acciones importantes secundarias que no deben competir visualmente con la primaria. |
| **Destructive** (`destructive`) | Eliminar, Borrar cuenta (Final) | Fondo rojo sólido (`#dc2626`), texto blanco. Resalta el peligro de la acción. | Acciones irreversibles en modales de confirmación. |
| **Ghost / Tertiary** (`ghost`) | Cancelar, Cerrar, Volver, Descartar | Sin fondo ni borde; fondo sutil en *hover*. | Acciones de baja prioridad, escapes o navegación neutra. |
| **Ghost Destructive** (`ghost-destructive`) | Borrar (Gatillador) | Transparente, texto rojo. Hover rojo sutil. | Gatilladores de eliminación en formularios o tablas, antes de la confirmación. |

### 2. Tokens de Geometría y Dimensiones en `Button.tsx`
* **Small (`sm`):** Altura `h-8`, Padding `px-3`, Texto `text-[13px] font-medium`. Uso: Tablas, toolbars compactas.
* **Medium (`md` - Default):** Altura `h-10`, Padding `px-4`, Texto `text-[14px]`. Uso: Estándar general.
* **Large (`lg`):** Altura `h-12`, Padding `px-6`, Texto `text-[16px]`. Uso: Formularios principales (Login/Register).
* **Icon (`icon`):** Padding cuadrado `p-2`. Uso: Botones que solo contienen un icono (e.g. Ojo de contraseña).
* **Border Radius:** `md` (`8px`) estandarizado a través de `--radius-md`.
* **Gap entre icono y texto:** `gap-2` (`8px`).
* **Transición:** `all 150ms cubic-bezier(0.4, 0, 0.2, 1)`.

### 3. Estados e Interacción (vía globals.css)
* **Primary:** Default: Background `var(--color-primary)` | Color `#000`. Hover: Agrega `box-shadow: 0 0 14px rgba(0, 168, 107, 0.4)`. Active: `transform: scale(0.98)`. Disabled: `opacity: 0.5` | `cursor: not-allowed` | quita shadow/transform.
* **Destructive:** Default: Background `#dc2626` | Color `#ffffff`. Hover: Background `#b91c1c` | `box-shadow: 0 0 14px rgba(220, 38, 38, 0.4)`. Active: `transform: scale(0.98)`.
* **Ghost / Tertiary:** Default: Background `transparent` | Sin borde | Color `var(--color-on-surface-muted)`. Hover: Background `rgba(255, 255, 255, 0.06)` | Color `var(--color-on-surface)`. Active: Background `rgba(255, 255, 255, 0.1)`.

### 4. Reglas de Composición y UX
1. **Orden en diálogos y modales:** `[ Cancelar (Ghost) ]` a la izquierda. `[ Aceptar (Primary) / Eliminar (Destructive) ]` a la derecha.
2. **Evitar conflictos primarios:** Nunca dos botones primarios juntos. "Guardar" es Primario, "Cancelar" es Ghost.
3. **Casing (Mayúsculas y Minúsculas) - ESTRICTO:** **NUNCA** uses ALL CAPS ni all lowercase. Usa siempre **Sentence case** o **Title Case**.
4. **Flujo de eliminación segura (2 pasos):** Paso 1 (Gatillador): Botón `ghost-destructive`. Paso 2 (Modal): Botón `destructive` rojo sólido, compitiendo con un `ghost` para Cancelar.
5. **Estado de Carga (Loading):** Añadir prop `disabled={isSaving}` al botón, cambiar texto por "Guardando..." o "Eliminando...".

## Design Token Reference (globals.css)
All tokens below MUST live in `globals.css` inside `@theme { ... }`.
```css
@import "tailwindcss";

@theme {
  /* --- Brand --- */
  --color-primary: #00a86b;
  --color-primary-dim: #59de9b;

  /* --- Dark Surface Scale --- */
  --color-surface: #131315;
  --color-surface-low: #1c1b1d;
  --color-surface-mid: #201f22;
  --color-surface-high: #2a2a2c;
  --color-surface-highest: #353437;
  --color-on-surface: #e5e1e4;
  --color-on-surface-muted: #bccabe;

  /* --- Light Surface Scale --- */
  --color-surface-light: #f8f9fa;
  --color-surface-light-mid: #eef0ee;
  --color-on-surface-light: #1a1c1a;

From 2004sfm/vaultlock, MIT.

More from 2004sfm/vaultlock