Folder structure
A map of the template folder. Each folder has one job, so you always know where a change belongs.
#The template folder
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
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
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
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:
import { Button } from '@/components/ui/Button';
import { Button } from '../../components/ui/Button';
Use the @/ form. It does not break when you move a file.