201 lines
6.7 KiB
Markdown
201 lines
6.7 KiB
Markdown
# Soft UI Dashboard Tailwind — Project Initialization Guide
|
|
|
|
Read this file first. It tells you exactly how to bootstrap a new project so it is visually identical to the Soft UI Dashboard Tailwind design. After completing setup, use `design-system.md` for all component and styling decisions.
|
|
|
|
Everything is self-hosted — no CDN dependencies at runtime.
|
|
|
|
---
|
|
|
|
## Step 1 — Copy the bundled assets into your project
|
|
|
|
All required CSS and font files are included in this `setup/` folder under `public/`. Copy them directly into your project's public directory:
|
|
|
|
```bash
|
|
cp -r path/to/setup/public/assets public/
|
|
```
|
|
|
|
This places:
|
|
```
|
|
public/assets/css/
|
|
soft-ui-dashboard-tailwind.css ← full compiled Tailwind CSS (all custom utilities)
|
|
nucleo-icons.css ← Nucleo icon font CSS
|
|
nucleo-svg.css ← Nucleo SVG icon CSS
|
|
public/assets/fonts/
|
|
nucleo-icons.{eot,ttf,woff,woff2,svg}
|
|
nucleo.{eot,ttf,woff,woff2}
|
|
```
|
|
|
|
No source project required — these files are self-contained in `setup/`.
|
|
|
|
---
|
|
|
|
## Step 2 — Download Open Sans and Font Awesome (self-hosted)
|
|
|
|
Run the provided download script from your project root. It fetches Open Sans woff2 files and Font Awesome Free 6, places them in the correct directories, and copies `open-sans.css` into your CSS folder.
|
|
|
|
```bash
|
|
bash path/to/setup/get-fonts.sh
|
|
```
|
|
|
|
This creates:
|
|
```
|
|
public/assets/css/
|
|
open-sans.css ← @font-face declarations for Open Sans
|
|
fontawesome/
|
|
all.min.css ← Font Awesome styles
|
|
webfonts/ ← FA woff2 + woff files
|
|
public/assets/fonts/
|
|
open-sans/ ← Open Sans woff2 files (weights 300/400/600/700)
|
|
```
|
|
|
|
If `curl` or `unzip` are not available, see the manual download instructions at the bottom of this file.
|
|
|
|
---
|
|
|
|
## Step 3 — Add `<head>` links to every HTML template
|
|
|
|
Every page must load these stylesheets, in this exact order:
|
|
|
|
```html
|
|
<!-- Open Sans (self-hosted) -->
|
|
<link href="/assets/css/open-sans.css" rel="stylesheet" />
|
|
|
|
<!-- Font Awesome Free 6 (self-hosted) -->
|
|
<link href="/assets/css/fontawesome/all.min.css" rel="stylesheet" />
|
|
|
|
<!-- Nucleo Icons (self-hosted, copied from source in Step 1) -->
|
|
<link href="/assets/css/nucleo-icons.css" rel="stylesheet" />
|
|
<link href="/assets/css/nucleo-svg.css" rel="stylesheet" />
|
|
|
|
<!-- Soft UI Dashboard CSS (self-hosted, copied from source in Step 1) -->
|
|
<link href="/assets/css/soft-ui-dashboard-tailwind.css" rel="stylesheet" />
|
|
```
|
|
|
|
No external requests are made at runtime.
|
|
|
|
---
|
|
|
|
## Step 4 — Set required `<body>` classes
|
|
|
|
Every page body tag must have these exact classes:
|
|
|
|
```html
|
|
<body class="m-0 font-sans antialiased font-normal text-base leading-default bg-gray-50 text-slate-500">
|
|
```
|
|
|
|
| Class | Effect |
|
|
|-------|--------|
|
|
| `font-sans` | Open Sans font |
|
|
| `antialiased` | Font smoothing |
|
|
| `font-normal` | Weight 400 default |
|
|
| `text-base` | 1rem base font size |
|
|
| `leading-default` | Line-height 1.6 |
|
|
| `bg-gray-50` | Page background `#f8f9fa` |
|
|
| `text-slate-500` | Default text `#67748e` |
|
|
|
|
---
|
|
|
|
## Step 5 — Use `base.html` as your layout shell
|
|
|
|
The file `setup/base.html` is a complete, working HTML starter with all local asset paths already set. Copy it and adapt it for your framework's templating system:
|
|
|
|
**Laravel (Blade):**
|
|
Save as `resources/views/layouts/app.blade.php`, replace static content with `@yield` / `@section` directives. Reference assets with `{{ asset('assets/css/...') }}`.
|
|
|
|
**Go / Gin (html/template):**
|
|
Save as `templates/layouts/base.html`. Replace static content with `{{block "content" .}}{{end}}`. Serve static files with:
|
|
```go
|
|
router.Static("/assets", "./public/assets")
|
|
```
|
|
|
|
**Go / Gin (templ):**
|
|
Convert the base.html structure into a `templ` layout component.
|
|
|
|
---
|
|
|
|
## Step 6 (Optional) — Full Tailwind build pipeline
|
|
|
|
Only needed if you want to write new custom utility classes not already in the copied CSS. The pre-built CSS from Step 1 contains the full compiled output and is sufficient for most cases.
|
|
|
|
If you need the build pipeline:
|
|
|
|
```bash
|
|
npm init -y
|
|
npm install -D tailwindcss@^3 autoprefixer postcss postcss-cli
|
|
```
|
|
|
|
Copy `setup/tailwind.config.js` into your project root.
|
|
|
|
Create `src/styles.css`:
|
|
```css
|
|
@tailwind base;
|
|
@tailwind components;
|
|
@tailwind utilities;
|
|
```
|
|
|
|
Update `package.json`:
|
|
```json
|
|
"scripts": {
|
|
"build:css": "tailwindcss build -i src/styles.css -o public/assets/css/soft-ui-dashboard-tailwind.css",
|
|
"watch:css": "tailwindcss build -i src/styles.css -o public/assets/css/soft-ui-dashboard-tailwind.css --watch"
|
|
}
|
|
```
|
|
|
|
Update `tailwind.config.js` `content` array to match your template paths:
|
|
```js
|
|
// Laravel Blade:
|
|
content: ["./resources/views/**/*.blade.php", "./resources/js/**/*.js"]
|
|
|
|
// Go html/template:
|
|
content: ["./templates/**/*.html"]
|
|
|
|
// Go templ:
|
|
content: ["./templates/**/*.templ", "./**/*.go"]
|
|
```
|
|
|
|
---
|
|
|
|
## What to read next
|
|
|
|
Once setup is complete, give Claude these files as context for all design decisions:
|
|
|
|
1. **`../design-system.md`** — Component patterns, colors, spacing, typography, and Quick-Start Rules. Primary reference for building any UI element.
|
|
2. **`../tokens.json`** — Design token values (colors, spacing, shadows, breakpoints).
|
|
3. **`../conformity.md`** — Feed this + generated code to Claude to score conformity.
|
|
|
|
---
|
|
|
|
## Critical classes — most commonly misused
|
|
|
|
| Element | Wrong | Right |
|
|
|---------|-------|-------|
|
|
| Cards | `shadow-xl rounded-lg` | `shadow-soft-xl rounded-2xl` |
|
|
| Button hover | `hover:shadow-lg` | `hover:shadow-soft-2xl hover:scale-102` |
|
|
| Transitions | `ease-in-out` | `ease-soft-in` or `ease-nav-brand` |
|
|
| Page background | `bg-white` | `bg-gray-50` |
|
|
| Default text | `text-gray-600` | `text-slate-500` |
|
|
| Sidebar width | `w-64` | `max-w-62.5` (15.625rem) |
|
|
| Main content offset | `ml-64` | `xl:ml-68.5` |
|
|
| Icon boxes | bare icon | `h-8 w-8 rounded-lg flex items-center justify-center` + gradient bg |
|
|
| Gradient accent | `bg-purple-500` | `bg-gradient-to-tl from-purple-700 to-pink-500` |
|
|
| Input focus | `focus:ring` | `focus:shadow-soft-primary-outline focus:border-fuchsia-300` |
|
|
|
|
---
|
|
|
|
## Manual font download (if get-fonts.sh can't run)
|
|
|
|
### Open Sans
|
|
1. Go to: https://fonts.google.com/specimen/Open+Sans
|
|
2. Select weights: 300, 400, 600, 700 (normal + italic for each)
|
|
3. Download the zip, extract the woff2 files
|
|
4. Rename to match the pattern: `open-sans-{weight}.woff2` and `open-sans-{weight}italic.woff2`
|
|
5. Place in `public/assets/fonts/open-sans/`
|
|
6. Copy `setup/open-sans.css` → `public/assets/css/open-sans.css`
|
|
|
|
### Font Awesome Free
|
|
1. Go to: https://github.com/FortAwesome/Font-Awesome/releases
|
|
2. Download `fontawesome-free-6.x.x-web.zip`
|
|
3. From the zip, copy:
|
|
- `css/all.min.css` → `public/assets/css/fontawesome/all.min.css`
|
|
- `webfonts/` (woff2 + woff files only) → `public/assets/css/fontawesome/webfonts/`
|