> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ooneex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> A reusable front-end design system — components, hooks, icons, fonts, and styles — packaged as a special design module and consumed by your SPA.

A **design module** holds your application's front-end design system: the React UI layer. It bundles components, hooks, icons, fonts, styles, and front-end utilities into one place so every screen draws from the same primitives. It is not backend logic — there are no controllers, services, or repositories here. A design module is purely the visual and interactive layer that a [Single Page App](/spa/overview) renders.

It lives under `modules/<kebab-name>/` like any other module, but its `<name>.yml` declares `type: "design"`. That single flag changes how the framework treats it: a design module is a front-end asset library, not a participant in the backend request pipeline.

## Why a design module

* **One source of UI truth.** Buttons, inputs, dialogs, tables, and the rest live in a single module, so every SPA pulls from the same components, icons, and fonts instead of redefining them per screen.
* **Front-end, not backend.** A design module carries only the React layer. It is never registered into `AppModule` or `SharedModule`, because it has nothing to do with handling HTTP or WebSocket requests.
* **Sourced from a skeleton.** Its `src/` is not a blank local template — `ooneex design:create` pulls the design system from the upstream [`skeleton-design`](https://github.com/ooneex/skeleton-design.git) repository, so you start with a complete, production-ready set of primitives.
* **Organized by asset kind.** Components, hooks, icons, fonts, styles, and utils each get their own folder, so finding and extending a primitive is predictable.
* **Consumed by SPAs.** The design module is the UI library your SPA imports from — see [SPA](/spa/overview) for how the two connect.

## How it differs from other modules

A design module is still a module, but it plays a different role than a regular [Module](/module/overview) or a microservice.

| Concern                | Design module                                                   | Regular module / microservice                                  |
| ---------------------- | --------------------------------------------------------------- | -------------------------------------------------------------- |
| Contents               | React UI assets: components, hooks, icons, fonts, styles, utils | Backend logic: controllers, services, repositories, middleware |
| `type` in `<name>.yml` | `"design"`                                                      | `app`, `shared`, or a microservice type                        |
| Backend registration   | Never registered into `AppModule` / `SharedModule`              | Wired into the backend request pipeline                        |
| Source of `src/`       | Pulled from the `skeleton-design` repository                    | Scaffolded from local templates                                |
| Who consumes it        | Imported by a SPA as a UI library                               | Invoked by the request pipeline                                |

## How it works

`ooneex design:create` scaffolds a base module, marks it `type: "design"`, then pulls the design source from the `skeleton-design` GitHub repository and installs that design's dependencies into your project. The result is a module whose `src/` mirrors the skeleton — a full design system you can use as-is or extend.

| Folder        | What it holds                                                                                                                           |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `components/` | React `.tsx` UI primitives (\~50): accordion, avatar, badge, button, card, dialog, form, input, select, table, tabs, tooltip, and more. |
| `hooks/`      | Reusable React hooks shared across components and screens.                                                                              |
| `icons/`      | SVG icons in fill and outline variants and multiple sizes.                                                                              |
| `fonts/`      | Bundled web fonts (Space Grotesk) with their `@font-face` CSS.                                                                          |
| `styles/`     | Global stylesheets applied across the design system.                                                                                    |
| `utils/`      | Front-end helpers such as `cn` for composing class names.                                                                               |

A design module sits alongside your other modules but stays out of the backend pipeline:

```text theme={null}
modules/
  app/                 # backend: type "app"
  shared/              # backend: type "shared"
  design/              # front-end: type "design"
    design.yml         # declares type: "design"
    src/
      components/
      hooks/
      icons/
      fonts/
      styles/
      utils/
```

Because the `type` is `"design"`, the module is treated as a front-end asset library. Only modules with `type: "design"` can be removed with `ooneex design:remove` — the `app` and `shared` modules are protected and cannot be deleted this way.

## Where to go next

* [Structure](/design-system/structure) — the folder layout in detail and what each asset kind contains.
* [Usage](/design-system/usage) — importing components, hooks, icons, fonts, and utils into a SPA.
* [Create](/design-system/create) — `ooneex design:create` and how the skeleton is pulled.
* [Remove](/design-system/remove) — `ooneex design:remove` and the protection on `app` / `shared`.
* [Module](/module/overview) — how regular backend modules differ from a design module.
* [SPA](/spa/overview) — the Single Page App that consumes the design system.