Welcome. This file covers what is specific to this repository; general open-source etiquette is assumed. How we treat each other is in the Code of Conduct.
| Branch | What it is |
|---|---|
main |
What is published. The site and the registry at deeplethe.github.io/solid-glass are built from it. Only maintainers merge into it, from dev |
dev |
Integration branch. Every contribution lands here first |
Your path as a contributor:
git switch dev && git pull
git switch -c fix/some-thing # branch off dev, not main
# make changes, commit with -s (see DCO below)
git push -u origin fix/some-thingThen open a PR with base dev, not main. A maintainer merges once CI and review pass.
Merging dev → main is done by maintainers on their own schedule; contributors don't need to think about it. Two rules keep the two branches from drifting apart, and both are for maintainers:
- Back-merge
mainintodevright after a release. Thedev → mainmerge commit lives only onmain, so without thismainreads as ahead even though the trees are identical, and the gap grows by one every release. - Urgent fixes go through
devtoo. A PR opened straight againstmainis the one thing that makes the two branches genuinely diverge, and then someone has to reconcile them by hand.
A merge into main is a release: the site is rebuilt and the registry that shadcn add reads changes for everyone. Nothing reaches users before that.
Both branches are protected: pull request required, CI (web) must pass, no force pushes, no deletions, and admins are held to the same rules.
| Change | What to do |
|---|---|
| Bug fixes, a component the theme missed, docs, examples | Open a PR directly |
| A new component or block, a dependency | Open an issue first and describe the use case |
| The material itself (a token's meaning, the four rules, what a state looks like), the registry's addresses or item names | Discuss in an issue before writing code |
The last row is what other people's projects depend on. A variable renamed in src/solid-glass.css, or an item renamed in the registry, breaks an installation that was working.
Requires Node 22+ and npm.
npm install
npm run dev # http://localhost:5191/dev/examples (development only) mounts every example on one page and lists any that fail. It takes ?q=button,card to show some of them, ?theme=light, ?hover=<selector> to show what matches as if the pointer were on it, and ?click=<selector> to press something and look at what it opens.
CI runs exactly this. Green locally means green in CI:
npm ci
npm run docs # the documentation and the registry are generated; the types depend on them
npm run typecheck
npm run buildThere are no unit tests: what this repository makes is how things look. So a change is checked by looking, and the pull request says what was looked at:
/dev/examplesreports0 failed.- The components the change touches, in both themes. Dark is the material as designed; light is where a rule written for dark most often goes wrong.
- Open states too: a menu, a dialog, a hovered row. Most of what has been missed was only visible open.
Nothing is a flat fill. Every surface is finished at its edge: a line of light along the top, a hairline round it, a shadow where it stands off the page. A component that arrives as a plain block of colour is not done. The four rules are on the Material page; hold a change to them.
The stylesheet restyles; it does not ask for edits. src/solid-glass.css finds each part of a shadcn/ui component by the data-slot and the classes it already carries. A fix that only works after editing a file in src/components/ui/ does nothing for someone who installed the stock component. Fix it in the stylesheet, and check it against the component as shadcn/ui ships it.
Lines of light are drawn inside the edge. An inset shadow sits inside the border. On an element that keeps a border, the border is the hairline, one colour all the way round, and the line of light is an inset shadow just inside it. A border with a brighter top breaks at rounded corners; a border left between an inset line and an outer ring reads as a second edge. Both have been shipped and taken back.
No colour of its own. The glass is neutral grey. Hue is for what it says: a status, a failing step, a series in a chart. A pane that takes the colour of what is behind it is liquid glass, which this is not.
One state. Hovered, chosen and held open wear the same small pane of clear glass. A new way of showing "this one" needs a reason.
A component of Solid Glass's own comes whole. src/components/ui/<name>.tsx written like a shadcn/ui component (function components, a data-slot on every part, cn()), at least one example in src/examples/, and its page in content/solid/. The registry is built from those three.
A block must run in a clean project. Solid Glass's own blocks are single files at the top of src/blocks/ and are published in the registry. They import only what the registry or shadcn/ui can install, and carry made-up data: no real names, products or addresses.
A picture that changes gets a new file name. GitHub serves a README's pictures from one address per file and browsers keep them; banner-5.webp becomes banner-6.webp, and the README points at the new one. Pictures are WebP.
Comments explain why. This repository comments densely and records the traps it fell into ("a white rim on a light fill does not show"). Follow that. A comment restating what the code does will be asked to go.
Commit messages: one English sentence, stating the motivation. Skim git log for the register.
Every workflow declares its own permissions:. contents: read for anything that just builds.
The stock components in src/components/ui/, the examples in src/examples/, the pages in content/components/, the preview cards in src/create/cards/ and the blocks in folders under src/blocks/ are shadcn/ui's, under the MIT License; NOTICE.md says which and from which commit. Improvements to those belong upstream, in shadcn-ui/ui. Changes here are for the material.
We use the DCO, not a CLA. You keep the copyright on your code; you are certifying that you have the right to submit it under the MIT License.
Commit with -s and git adds the line for you:
git commit -s -m "Fix the thing"which appends:
Signed-off-by: Your Name <your@email>
Forgot? git commit --amend -s for the last commit, or git rebase --signoff HEAD~3 for several (adjust the count), then git push -f.
Use a consistent identity you answer to — a GitHub account with history under it counts — and an address that reaches you; a noreply address tied to that account is fine. No anonymous or throwaway contributions.
By contributing you agree that your work is released under the MIT License.