references/starting.md
Starting a project from it
This design system ships as a repo you clone per project, not a package you install. That is deliberate: the components are meant to be edited, and a versioned dependency would fight you every time a client wants their own wording, spacing, or section order.
Clone and detach
# 1. clone into the new project folder
git clone git@gitlab.com:software-consultancy/ui-apple.git my-client-project
cd my-client-project
# 2. detach from the starter, so commits go to the project and not back here
rm -rf .git && git init -b main
# 3. point at the project's own remote
git remote add origin git@gitlab.com:<group>/<my-client-project>.git
# 4. install and run
pnpm install && pnpm devStep 2 is the one people skip, and skipping it means the first git push tries to write to the starter repo.
Retitle checklist
Search and replace ui-apple, then update:
package.json-name,descriptionREADME.md- replace wholesale; it documents the starter, not the projectsrc/app/layout.tsx-metadata.title,metadata.descriptionsrc/components/pages/- renameHomePage.tsxto the real page
Leaving the starter's metadata in place ships ui-apple as the browser tab title and the OpenGraph description, which is the kind of thing that survives to production.
Keep versus replace
| Keep as-is | Replace |
|---|---|
src/components/atoms/, molecules/, organisms/, templates/ - these are the design system | src/components/pages/ - placeholders; write the real pages |
src/app/globals.css - the tokens are the whole point | src/app/page.tsx and the per-level showcase routes - delete or repurpose |
src/lib/cn.ts | src/lib/showcase.tsx - only useful if keeping the component showcase |
tsconfig.json, next.config.ts, postcss.config.mjs | README.md |
The showcase routes render every component at every variant. They are genuinely useful during design review - keep them behind a route you do not link, and delete them before launch.
Where the work actually goes
Components are unopinionated about content. Filling them with the client's words and images is most of the job, and the temptation at that point is to add a variant "just for this section". Resist it: reach for an existing organism with different content first, and only add a component when two pages need the same new shape.
Deploying static
The repo has been run on GitLab Pages, which needs assetPrefix set in next.config.ts for a project-subpath deployment. If assets 404 in production but work locally, that is the setting to check first.