Skip to content
DocsStart here
Start here

Folder structure

A map of the template folder. Each folder has one job, so you always know where a change belongs.

#The template folder

Folders
template/
  index.html            # the HTML page, the fonts and the theme script
  package.json          # dependencies and npm commands
  vite.config.ts        # dev server port, the @ alias, build chunks
  tsconfig*.json        # TypeScript settings
  eslint.config.js      # lint rules
  .stylelintrc.json     # style sheet lint rules
  .prettierrc           # formatting rules
  .nvmrc                # the Node.js version
  public/
    favicon.svg         # the browser tab icon
  src/
    main.tsx            # starts the app: theme, styles, React
    App.tsx             # the router and the shell chooser
    components/         # everything you build pages from
    context/            # React context for the Appearance drawer
    data/               # the page list and the demo data
    hooks/              # small React hooks
    lib/                # plain TypeScript helpers
    pages/              # one file per page
    styles/             # every style sheet

#src/components

Folders
components/
  ui/          # the kit: Button, Input, Switch, Table, Dialog, Toast and more
  charts/      # Line, Spark, Ring, Bars, Dial, Gauge and the Chart catalog
  motion/      # Stagger, CountUp, Draw and useReducedMotion
  patterns/    # whole-page layouts: ListPage, DetailPage, FormPage, AppFrame...
  shell/       # the frame around pages: Keypad, PageHead, CommandPalette...
Folder What is inside Read more
ui/ About 30 components. Each one renders one .am-<name> CSS class. Components
charts/ Seven chart components, all drawn with Apache ECharts. Charts
motion/ Entrance, count and draw helpers. Motion
patterns/ Page layouts that most pages are built on. Page patterns
shell/ The sidebar, page header, command palette, Appearance drawer and the three shells. Pages and routing

Every folder has an index.ts that exports its components, but the pages import each file directly, for example import { Button } from '@/components/ui/Button'.

#src/pages

Folders
pages/
  pageRegistry.ts     # finds every page file and gives it a route
  Placeholder.tsx     # shown for a route that has no page file yet
  home/               # Overview.tsx, Building.tsx, FloorPlan.tsx, Wall.tsx
  energy/
  climate/
  devices/
  work/
  access/
  residents/
  workspace/
  account/
  ui/                 # the 13 design kit pages
  auth/               # the 7 sign-in pages
  error/              # the 6 error pages

The file name decides the URL. src/pages/energy/MeterDetail.tsx is the page at /energy/meter-detail. You never write a <Route> by hand. Pages and routing explains how.

#src/data

File What it is
nav-manifest.json The list of every page: its URL, title, icon, shell and search words. The sidebar, breadcrumbs, command palette and router all read it.
demo/*.json The demo data, one file per area: building, energy, climate, devices, work, access, residents, workspace, account, team and counters.
demo/types.ts The TypeScript types for the demo data.
demo/index.ts Exports the data, the demo clock NOW and a few lookup helpers.

#src/styles

Folders
styles/
  app.css             # the one CSS entry; imports everything in order
  tokens/
    _primitives.css   # raw values: color scales, spacing, radii
    _roles.css        # what components read: --am-bg, --am-ink, --am-accent...
    _themes.css       # graphite, compact, light direction, flat keys
    _typography.css   # font families, sizes, weights
    _motion.css       # durations, easing curves, reduced motion
    _charts.css       # the chart colors
    _recipes.css      # .am-raised, .am-well, .am-key: the three surfaces
  base.css            # page defaults
  shell.css           # the app frame
  nav.css             # the sidebar keypad and its menus
  components.css      # the look of every component
  utilities.css       # small layout classes

The Theming page explains the token files.

#src/lib and src/hooks

File What it does
lib/theme.ts The appearance settings: reads and writes the attributes on <html>. See Appearance settings.
lib/manifest.ts Typed access to nav-manifest.json: page lookup, breadcrumbs and palette search.
lib/nav.ts Small navigation helpers: active group, previous and next page.
lib/format.ts Number, date, currency and unit formatters, plus cx() for joining class names.
lib/storage.ts Safe localStorage access. It never throws, even when storage is blocked.
hooks/useHotkey.ts Keyboard shortcuts, for example useHotkey('mod+k', open).
hooks/useFocusTrap.ts Keeps keyboard focus inside a dialog or drawer.
hooks/useClickOutside.ts Runs a function when you click outside an element.
hooks/useMediaQuery.ts Returns true while a CSS media query matches.
hooks/useLocalStorage.ts A useState that is saved in localStorage.

#The @ alias

@/ means src/. It is set in vite.config.ts and tsconfig.app.json, so these two lines are the same:

TSX
import { Button } from '@/components/ui/Button';
import { Button } from '../../components/ui/Button';

Use the @/ form. It does not break when you move a file.