@lukoweb/apitogo 0.2.54 → 0.2.57

package/docs/customization/colors-theme.mdx

@@ -1,278 +1,255 @@
----
-sidebar_icon: paintbrush
-title: Colors & Theme
-description:
-  Customize your APIToGo site's colors and theme with flexible options, including light/dark modes,
-  custom CSS, and shadcn registry integration.
----
-
-APIToGo provides flexible theming options allowing you to customize colors, import themes from
-[shadcn registries](https://ui.shadcn.com/docs/registry), and add custom CSS. You can create
-cohesive light and dark mode experiences that match your brand.
-
-:::tip
-
-Try out the interactive [Theme Playground](/docs/theme-playground) to experiment with colors and see
-real-time previews of your theme changes.
-
-:::
-
-The theme system is built on [shadcn/ui theming](https://ui.shadcn.com/docs/theming) and
-[Tailwind v4](https://tailwindcss.com), giving us a great foundation to build upon:
-
-- **CSS variables** match `shadcn/ui` conventions
-- **Tailwind v4** CSS variable system for modern styling
-- **Theme editors** like [tweakcn](https://tweakcn.com/) work out of the box
-- **Shadcn registries** are supported
-- **Landing homepage**, **portal footer**, and **MCP-generated custom pages** all use the same
-  semantic tokens (`bg-primary`, `text-muted-foreground`, `border-border`, etc.)
-
-## Custom Colors
-
-You can manually define colors for both light and dark modes, either by extending the
-[default theme](#default-theme) or creating a completely custom theme. Colors can be specified as
-hex values, RGB, HSL, OKLCH, etc. - basically anything that is supported by
-[Tailwind CSS](https://tailwindcss.com):
-
-```ts title=config
-const config = {
-  theme: {
-    light: {
-      background: "#ffffff",
-      foreground: "#020817",
-      card: "#ffffff",
-      cardForeground: "#020817",
-      popover: "#ffffff",
-      popoverForeground: "#020817",
-      primary: "#0284c7",
-      primaryForeground: "#ffffff",
-      secondary: "#f1f5f9",
-      secondaryForeground: "#020817",
-      muted: "#f1f5f9",
-      mutedForeground: "#64748b",
-      accent: "#f1f5f9",
-      accentForeground: "#020817",
-      destructive: "#ef4444",
-      destructiveForeground: "#ffffff",
-      border: "#e2e8f0",
-      input: "#e2e8f0",
-      ring: "#0284c7",
-      radius: "0.5rem",
-    },
-    dark: {
-      background: "#020817",
-      foreground: "#f8fafc",
-      card: "#020817",
-      cardForeground: "#f8fafc",
-      popover: "#020817",
-      popoverForeground: "#f8fafc",
-      primary: "#0ea5e9",
-      primaryForeground: "#f8fafc",
-      secondary: "#1e293b",
-      secondaryForeground: "#f8fafc",
-      muted: "#1e293b",
-      mutedForeground: "#94a3b8",
-      accent: "#1e293b",
-      accentForeground: "#f8fafc",
-      destructive: "#ef4444",
-      destructiveForeground: "#f8fafc",
-      border: "#1e293b",
-      input: "#1e293b",
-      ring: "#0ea5e9",
-      radius: "0.5rem",
-    },
-  },
-};
-```
-
-## Available Theme Variables
-
-| Variable                | Description                           |
-| ----------------------- | ------------------------------------- |
-| `background`            | Main background color                 |
-| `foreground`            | Main text color                       |
-| `card`                  | Card background color                 |
-| `cardForeground`        | Card text color                       |
-| `popover`               | Popover background color              |
-| `popoverForeground`     | Popover text color                    |
-| `primary`               | Primary action color                  |
-| `primaryForeground`     | Text color on primary backgrounds     |
-| `secondary`             | Secondary action color                |
-| `secondaryForeground`   | Text color on secondary backgrounds   |
-| `muted`                 | Muted/subtle background color         |
-| `mutedForeground`       | Text color for muted elements         |
-| `accent`                | Accent color for highlights           |
-| `accentForeground`      | Text color on accent backgrounds      |
-| `destructive`           | Color for destructive actions         |
-| `destructiveForeground` | Text color on destructive backgrounds |
-| `border`                | Border color                          |
-| `input`                 | Input field border color              |
-| `ring`                  | Focus ring color                      |
-| `radius`                | Border radius value                   |
-
-:::note
-
-While shadcn/ui defines additional theme variables, APIToGo currently uses only these core
-variables.
-
-:::
-
-## shadcn Registry Integration
-
-The easiest way to customize your theme is by using a Shadcn registry theme. For example you can use
-the great [tweakcn](https://tweakcn.com/) visual theme editor.
-
-### Using tweakcn Themes
-
-<Stepper>
-
-1. Visit [tweakcn.com](https://tweakcn.com/) to select a preset or customize your theme visually
-
-   <Framed align="start">![](./tweakcn0.webp)</Framed>
-   <Framed align="start">![](./tweakcn1.webp)</Framed>
-
-1. Copy the registry URL from the "Copy" section
-
-   <Framed align="start">![](./tweakcn2.webp)</Framed>
-
-1. Add it to your configuration:
-   ```ts title=config
-   const config = {
-     theme: {
-       registryUrl: "https://tweakcn.com/r/themes/northern-lights.json",
-     },
-   };
-   ```
-1. The theme will then be automatically imported with all color variables, fonts, and styling
-   configured for you 🚀
-
-   <Framed align="start">![](/tweakcn-northlight.png)</Framed>
-
-</Stepper>
-
-You can still override specific values if needed:
-
-```ts title=config
-const config = {
-  theme: {
-    registryUrl: "https://tweakcn.com/api/registry/theme/xyz123",
-    // Override specific colors
-    light: {
-      primary: "#0066cc",
-    },
-    dark: {
-      primary: "#3399ff",
-    },
-  },
-};
-```
-
-Alternatively, you can copy the CSS code and paste it into your `customCss` configuration:
-
-```ts title=config
-const config = {
-  theme: {
-    customCss: `
-      /* Copied CSS code */
-    `,
-  },
-};
-```
-
-## Custom CSS
-
-For advanced styling, you can add custom CSS either as a string or structured object:
-
-:::note
-
-Changes to `customCss` require restarting the development server to take effect.
-
-:::
-
-### CSS String
-
-```ts title=config
-const config = {
-  theme: {
-    customCss: `
-      .custom {
-        background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
-      }
-    `,
-  },
-};
-```
-
-### CSS Object
-
-```ts title=config
-const config = {
-  theme: {
-    customCss: {
-      ".custom": {
-        background: "linear-gradient(135deg, #667eea 0%, #764ba2 100%)",
-      },
-    },
-  },
-};
-```
-
-## Default Theme
-
-APIToGo comes with a built-in default theme based on
-[shadcn/ui zinc base colors](https://ui.shadcn.com/docs/theming#zinc). If you want to start
-completely from scratch without any default styling, you can disable the default theme:
-
-```ts title=config
-const config = {
-  theme: {
-    noDefaultTheme: true,
-    // Your custom theme configuration
-  },
-};
-```
-
-When `noDefaultTheme` is set to `true`, no default colors or styling will be applied, giving you
-complete control over your theme. Changing this requires to restart the development server.
-
-## Complete Example
-
-Here's a comprehensive example combining multiple theming approaches:
-
-```ts title=config
-const config = {
-  theme: {
-    // Import base theme from registry
-    registryUrl: "https://tweakcn.com/api/registry/theme/modern-blue",
-
-    // Override specific colors
-    light: {
-      primary: "#0066cc",
-      accent: "#f0f9ff",
-    },
-    dark: {
-      primary: "#3399ff",
-      accent: "#0c1b2e",
-    },
-
-    // Custom fonts
-    fonts: {
-      sans: "Inter",
-      mono: "JetBrains Mono",
-    },
-
-    // Additional custom styling
-    customCss: {
-      ".hero-section": {
-        background: "var(--primary)",
-        color: "var(--primary-foreground)",
-        padding: "2rem",
-        "border-radius": "var(--radius)",
-      },
-    },
-  },
-};
-```
-
-This configuration imports a base theme, customizes colors for both light and dark modes, sets
-fonts, and adds custom component styling.
+---
+sidebar_icon: paintbrush
+title: Colors & Theme
+description:
+  Customize your APIToGo site's colors and theme with flexible options, including light/dark modes,
+  custom CSS, and shadcn registry integration.
+---
+
+APIToGo provides flexible theming options allowing you to customize colors, import themes from
+[shadcn registries](https://ui.shadcn.com/docs/registry), and add custom CSS. You can create
+cohesive light and dark mode experiences that match your brand.
+
+:::tip
+
+Try out the interactive [Theme Playground](/docs/theme-playground) to experiment with colors and see
+real-time previews of your theme changes.
+
+:::
+
+The theme system is built on [shadcn/ui theming](https://ui.shadcn.com/docs/theming) and
+[Tailwind v4](https://tailwindcss.com), giving us a great foundation to build upon:
+
+- **CSS variables** match `shadcn/ui` conventions
+- **Tailwind v4** CSS variable system for modern styling
+- **Theme editors** like [tweakcn](https://tweakcn.com/) work out of the box
+- **Shadcn registries** are supported
+- **Landing homepage**, **portal footer**, and **MCP-generated custom pages** all use the same
+  semantic tokens (`bg-primary`, `text-muted-foreground`, `border-border`, etc.)
+
+## Where the theme lives
+
+The portal's theme is **`apitogo/portal/theme.json`**. `apitogo add portal` writes it with the
+default colors, so it changes nothing until you edit it. To keep it somewhere else, name the file in
+`portal.theme` in `apitogo.config.json`. Every example below is the content of that file.
+
+`apitogo check` reports a theme file that is not valid JSON.
+
+## Custom Colors
+
+You can manually define colors for both light and dark modes, either by extending the
+[default theme](#default-theme) or creating a completely custom theme. Colors can be specified as
+hex values, RGB, HSL, OKLCH, etc. - basically anything that is supported by
+[Tailwind CSS](https://tailwindcss.com):
+
+```json title=apitogo/portal/theme.json
+{
+  "light": {
+    "background": "#ffffff",
+    "foreground": "#020817",
+    "card": "#ffffff",
+    "cardForeground": "#020817",
+    "popover": "#ffffff",
+    "popoverForeground": "#020817",
+    "primary": "#0284c7",
+    "primaryForeground": "#ffffff",
+    "secondary": "#f1f5f9",
+    "secondaryForeground": "#020817",
+    "muted": "#f1f5f9",
+    "mutedForeground": "#64748b",
+    "accent": "#f1f5f9",
+    "accentForeground": "#020817",
+    "destructive": "#ef4444",
+    "destructiveForeground": "#ffffff",
+    "border": "#e2e8f0",
+    "input": "#e2e8f0",
+    "ring": "#0284c7",
+    "radius": "0.5rem"
+  },
+  "dark": {
+    "background": "#020817",
+    "foreground": "#f8fafc",
+    "card": "#020817",
+    "cardForeground": "#f8fafc",
+    "popover": "#020817",
+    "popoverForeground": "#f8fafc",
+    "primary": "#0ea5e9",
+    "primaryForeground": "#f8fafc",
+    "secondary": "#1e293b",
+    "secondaryForeground": "#f8fafc",
+    "muted": "#1e293b",
+    "mutedForeground": "#94a3b8",
+    "accent": "#1e293b",
+    "accentForeground": "#f8fafc",
+    "destructive": "#ef4444",
+    "destructiveForeground": "#f8fafc",
+    "border": "#1e293b",
+    "input": "#1e293b",
+    "ring": "#0ea5e9",
+    "radius": "0.5rem"
+  }
+}
+```
+
+## Available Theme Variables
+
+| Variable                | Description                           |
+| ----------------------- | ------------------------------------- |
+| `background`            | Main background color                 |
+| `foreground`            | Main text color                       |
+| `card`                  | Card background color                 |
+| `cardForeground`        | Card text color                       |
+| `popover`               | Popover background color              |
+| `popoverForeground`     | Popover text color                    |
+| `primary`               | Primary action color                  |
+| `primaryForeground`     | Text color on primary backgrounds     |
+| `secondary`             | Secondary action color                |
+| `secondaryForeground`   | Text color on secondary backgrounds   |
+| `muted`                 | Muted/subtle background color         |
+| `mutedForeground`       | Text color for muted elements         |
+| `accent`                | Accent color for highlights           |
+| `accentForeground`      | Text color on accent backgrounds      |
+| `destructive`           | Color for destructive actions         |
+| `destructiveForeground` | Text color on destructive backgrounds |
+| `border`                | Border color                          |
+| `input`                 | Input field border color              |
+| `ring`                  | Focus ring color                      |
+| `radius`                | Border radius value                   |
+
+:::note
+
+While shadcn/ui defines additional theme variables, APIToGo currently uses only these core
+variables.
+
+:::
+
+## shadcn Registry Integration
+
+The easiest way to customize your theme is by using a Shadcn registry theme. For example you can use
+the great [tweakcn](https://tweakcn.com/) visual theme editor.
+
+### Using tweakcn Themes
+
+<Stepper>
+
+1. Visit [tweakcn.com](https://tweakcn.com/) to select a preset or customize your theme visually
+
+   <Framed align="start">![](./tweakcn0.webp)</Framed>
+   <Framed align="start">![](./tweakcn1.webp)</Framed>
+
+1. Copy the registry URL from the "Copy" section
+
+   <Framed align="start">![](./tweakcn2.webp)</Framed>
+
+1. Add it to your configuration:
+   ```json title=apitogo/portal/theme.json
+   {
+     "registryUrl": "https://tweakcn.com/r/themes/northern-lights.json"
+   }
+   ```
+1. The theme will then be automatically imported with all color variables, fonts, and styling
+   configured for you 🚀
+
+   <Framed align="start">![](/tweakcn-northlight.png)</Framed>
+
+</Stepper>
+
+You can still override specific values if needed:
+
+```json title=apitogo/portal/theme.json
+{
+  "registryUrl": "https://tweakcn.com/api/registry/theme/xyz123",
+  "light": {
+    "primary": "#0066cc"
+  },
+  "dark": {
+    "primary": "#3399ff"
+  }
+}
+```
+
+Alternatively, you can copy the CSS code and paste it into your `customCss` configuration:
+
+```json title=apitogo/portal/theme.json
+{
+  "customCss": "/* the copied CSS */"
+}
+```
+
+## Custom CSS
+
+For advanced styling, you can add custom CSS either as a string or structured object:
+
+:::note
+
+Changes to `customCss` require restarting the development server to take effect.
+
+:::
+
+### CSS String
+
+```json title=apitogo/portal/theme.json
+{
+  "customCss": ".custom { background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); }"
+}
+```
+
+### CSS Object
+
+```json title=apitogo/portal/theme.json
+{
+  "customCss": {
+    ".custom": {
+      "background": "linear-gradient(135deg, #667eea 0%, #764ba2 100%)"
+    }
+  }
+}
+```
+
+## Default Theme
+
+APIToGo comes with a built-in default theme: teal on navy and white, the colors `theme.json` starts
+with. If you want to start completely from scratch without any default styling, you can disable the
+default theme:
+
+```json title=apitogo/portal/theme.json
+{
+  "noDefaultTheme": true
+}
+```
+
+When `noDefaultTheme` is set to `true`, no default colors or styling will be applied, giving you
+complete control over your theme. Changing this requires to restart the development server.
+
+## Complete Example
+
+Here's a comprehensive example combining multiple theming approaches:
+
+```json title=apitogo/portal/theme.json
+{
+  "registryUrl": "https://tweakcn.com/api/registry/theme/modern-blue",
+  "light": {
+    "primary": "#0066cc",
+    "accent": "#f0f9ff"
+  },
+  "dark": {
+    "primary": "#3399ff",
+    "accent": "#0c1b2e"
+  },
+  "fonts": {
+    "sans": "Inter",
+    "mono": "JetBrains Mono"
+  },
+  "customCss": {
+    ".hero-section": {
+      "background": "var(--primary)",
+      "color": "var(--primary-foreground)",
+      "padding": "2rem",
+      "border-radius": "var(--radius)"
+    }
+  }
+}
+```
+
+This configuration imports a base theme, customizes colors for both light and dark modes, sets
+fonts, and adds custom component styling.