bref-ui-themes 0.1.0 → 1.0.1

package/README.md

@@ -1,111 +1,167 @@
-# bref-ui-themes
+# Bref-ui themes
 
-Reusable Svelte 5 themes for [bref-ui](https://github.com/feuersteiner/bref-ui), with interactive demos and native CSS. Version 0.1.0 is an unpublished review candidate built on SvelteKit 3 and published Bref 2.2.0.
+Ready-to-use themes for [Bref-ui](https://github.com/feuersteiner/bref-ui), built
+with Svelte 5, native HTML and scoped CSS. Pick a visual style and compose familiar
+Bref components through a dedicated theme entry point.
 
-[Explore the showcase](https://feuersteiner.github.io/bref-ui-themes/) · [Bref documentation](https://feuersteiner.github.io/bref-ui/) · [Join Discord](https://discord.gg/JpgQRTUsVS)
+[![npm](https://img.shields.io/npm/v/bref-ui-themes?logo=npm)](https://www.npmjs.com/package/bref-ui-themes)
+[![Discord](https://img.shields.io/badge/Discord-Join-5865F2?logo=discord&logoColor=white)](https://discord.gg/JpgQRTUsVS)
+[![MIT license](https://img.shields.io/badge/license-MIT-blue)](https://github.com/feuersteiner/bref-ui/blob/main/LICENSE)
 
-## Local development
+Explore the [theme galleries](https://feuersteiner.github.io/bref-ui/themes) for
+component examples and interaction states, or browse the
+[Bref-ui documentation](https://feuersteiner.github.io/bref-ui/).
 
-Requires Bun 1.3.4 or newer. The scaffold uses Svelte 5, SvelteKit 3, Vite 8 and `svelte-package` 3.
+https://github.com/user-attachments/assets/3326a5c3-0573-4b40-bb8e-9a10da1fd6ac
+
+See New Paris, VS Code and Glassy in action. The
+[video app and storyboard](https://github.com/feuersteiner/bref-ui/tree/main/video-demo)
+are part of this repository.
+
+## Available themes
+
+| Theme                                                                      | Style                                           | Import                        |
+| -------------------------------------------------------------------------- | ----------------------------------------------- | ----------------------------- |
+| [New Paris](https://feuersteiner.github.io/bref-ui/themes/new-paris)       | Black and ivory, serif headings, paper overlays | `bref-ui-themes/new-paris`    |
+| [Glassy](https://feuersteiner.github.io/bref-ui/themes/glassy)             | Translucent controls and frosted overlays       | `bref-ui-themes/glassy`       |
+| [Crystal Code](https://feuersteiner.github.io/bref-ui/themes/crystal-code) | Light and dark frosted workbench                | `bref-ui-themes/crystal-code` |
+| [VS Code](https://feuersteiner.github.io/bref-ui/themes/vscode)            | Fixed-dark workbench                            | `bref-ui-themes/vscode`       |
+
+Each entry point exports twenty components, including `Theme`, `Button`, form
+controls, overlays and navigation. Importing one theme does not load the others.
+
+## Installation
+
+Install [bref-ui-themes from npm](https://www.npmjs.com/package/bref-ui-themes) in a Svelte 5 app:
 
 ```sh
-bun install
-bun run dev                     # http://localhost:5173
-bun run check
-bun run lint
-bun run package                 # library → dist; includes publint
-bun run build:site              # static showcase → build
-bun run build                   # site + library
-bun run preview                 # preview the production site
-bun pm pack                     # creates a local npm tarball; does not publish
+npm install bref-ui bref-ui-themes
+```
+
+Bref-ui 3 and Svelte 5 are peer dependencies. The custom text font remains optional.
+
+Import components from the theme's entry point:
+
+```svelte
+<script>
+	import { Theme, Button } from 'bref-ui-themes/new-paris';
+</script>
+
+<Theme><Button label="Save" /></Theme>
 ```
 
-The restored GitHub Pages workflow builds `build:site` on pushes to `main`, using the Pages base path and uploading `build`. To reproduce the project-path build locally:
+## Development
+
+Run `bun install` and `bun run dev` from the repository root. The docs site consumes
+public workspace source exports directly. Package-level `check`, `build` and `prepack`
+remain available here; `src/lib` holds published sources and `src/routes` is only
+a local library preview.
+
+Packing includes this README and a generated copy of the repository MIT license.
+Edit the root license; generated package copies are ignored.
+
+Shared types come directly from `bref-ui/types` and are re-exported as types from
+`bref-ui-themes`. The root entry does not aggregate components or load theme CSS.
+New Paris depends on Material Symbols and loads its variable fill font through Theme.
+
+## New Paris
+
+Black and ivory controls, serif typography and opaque paper overlays. All twenty components are exported through the theme subpath.
+
+Material Symbols icons load automatically with Theme. The custom text font, Inter,
+is optional to avoid adding unused font assets to apps; text falls back to system
+fonts. To match the gallery typography, install and import Inter:
 
 ```sh
-BASE_PATH=/bref-ui-themes bun run build:site
-BASE_PATH=/bref-ui-themes bun run preview # http://localhost:4173/bref-ui-themes/
+npm install @fontsource-variable/inter
 ```
 
-## Showcase and demo sites
+```svelte
+<script>
+	import '@fontsource-variable/inter/index.css';
+	import { Theme, Button } from 'bref-ui-themes/new-paris';
+</script>
+
+<Theme><Button label="Save" /></Theme>
+```
 
-Open the [showcase](http://localhost:5173/). The showcase uses base `bref-ui` Theme, Button, Surface, Pill and Icon components, default palette/styles, documentation fonts and the Bref logo. Each card uses an actual browser screenshot and links to the working site. Every demo provides a Showcase link; navigation between themes reloads the document to avoid retaining global CSS.
+The gallery uses the same public package exports at `/themes/new-paris`.
+
+## Glassy
+
+Translucent controls and frosted overlays with scoped component styling. All twenty components are exported through the theme subpath:
+
+```svelte
+<script>
+	import { Theme, Button } from 'bref-ui-themes/glassy';
+</script>
 
-| Demo          | Implemented interactions                                                                  | Site                                          | Theme demonstration                                         |
-| ------------- | ----------------------------------------------------------------------------------------- | --------------------------------------------- | ----------------------------------------------------------- |
-| Tasks         | Project creation/filtering, task status tabs, search, completion and task editing         | [/relay](http://localhost:5173/relay)         | [/themes/relay](http://localhost:5173/themes/relay)         |
-| House Shop    | Category tabs, furniture sorting, product dialogs, cart quantities and simulated checkout | [/forma](http://localhost:5173/forma)         | [/themes/forma](http://localhost:5173/themes/forma)         |
-| Site Reviewer | URL validation, simulated audit progress, history and finding review tabs                 | [/elsewhere](http://localhost:5173/elsewhere) | [/themes/elsewhere](http://localhost:5173/themes/elsewhere) |
+<Theme><Button label="Save" /></Theme>
+```
 
-![Tasks rendered demo](static/previews/relay.jpg)
-![House Shop rendered demo](static/previews/forma.jpg)
-![Site Reviewer rendered demo](static/previews/elsewhere.jpg)
+Material Symbols icons load automatically with Theme. Inter remains optional; to
+match the gallery typography, install `@fontsource-variable/inter` and import
+`@fontsource-variable/inter/index.css` in the app.
 
-**WIP:** VS Code, Liquid Glass and Minimalist Blocky are planned. They have no exports, demonstration routes or availability links.
+The gallery uses the same public package exports at `/themes/glassy`.
 
-## Library imports
+## Crystal Code
 
-Install the local tarball with `bun add ./bref-ui-themes-0.1.0.tgz`. Consumers need Svelte `^5.57.1` and Bref `^2.2.0` (peer dependencies). Fonts used by the themes are package dependencies.
+Light and dark frosted workbench controls with a complete component reference. All twenty components are exported through the theme subpath:
 
 ```svelte
-<script lang="ts">
-	import { Theme, Button } from 'bref-ui-themes/relay';
+<script>
+	import { Theme, Button } from 'bref-ui-themes/crystal-code';
 </script>
 
-<Theme>
-	<Button label="Create project" variant="filled" color="primary" />
-</Theme>
+<Theme><Button label="Save" /></Theme>
 ```
 
-The same API is available from each implemented theme:
+Material Symbols icons load automatically with Theme. Inter remains optional; to
+match the gallery typography, install and import it:
 
-```ts
-import { Theme, Button } from 'bref-ui-themes/forma';
-// Or: import { Theme, Button } from 'bref-ui-themes/elsewhere';
-// Namespace exports: import { Relay, Forma, Elsewhere } from 'bref-ui-themes';
+```sh
+npm install @fontsource-variable/inter
 ```
 
-Each entry exports `Theme`, `Button`, `Checkbox`, `Dialog`, `Icon`, `Pill`, `PillChoiceGroup`, `PillGroup`, `Popover`, `Progress`, `Select`, `Spinner`, `Surface`, `Tabs` and `TextInput`. `Theme` takes an optional `children` snippet. Controls retain Bref's props, native attributes and applicable bindings; their types remain imported from `bref-ui/types`.
+```svelte
+<script>
+	import '@fontsource-variable/inter/index.css';
+	import { Theme, Button } from 'bref-ui-themes/crystal-code';
+</script>
 
-### Tabs
+<Theme><Button label="Save" icon={{ name: 'check' }} /></Theme>
+```
+
+The gallery uses the same public package exports at `/themes/crystal-code`.
 
-`Tabs` uses Bref 2.2.0's readonly item data, required icon names and bindable string value. The consumer renders the selected content:
+## VS Code
+
+Fixed-dark workbench controls with native interactions and scoped styling. All twenty components are exported through the theme subpath:
 
 ```svelte
-<script lang="ts">
-	import { Theme, Tabs } from 'bref-ui-themes/relay';
-	import type { TabItemDataProps } from 'bref-ui/types';
-	let view = $state('overview');
-	const items = [
-		{ id: 'overview', label: 'Overview', icon: 'dashboard' },
-		{ id: 'activity', label: 'Activity', icon: 'history' },
-		{ id: 'reports', label: 'Reports', icon: 'monitoring', disabled: true }
-	] as const satisfies readonly TabItemDataProps[];
+<script>
+	import { Theme, Button } from 'bref-ui-themes/vscode';
 </script>
 
-<Theme>
-	<Tabs {items} bind:value={view} label="Project views" />
-	<div role="tabpanel" aria-label={items.find((item) => item.id === view)?.label} tabindex="0">
-		{#if view === 'overview'}<p>8 tasks open, 3 completed.</p>
-		{:else}<p>The navigation review was completed today.</p>{/if}
-	</div>
-</Theme>
+<Theme><Button label="Save" icon={{ name: 'check' }} /></Theme>
 ```
 
-Horizontal tabs accept `size="fit"` (default, scrolls on overflow) or `size="fill"`. Vertical tabs use `orientation="vertical"` without `size`. Optional `onChange`, `filled`, `transitionIn` and `transitionOut` retain the published API. Default indicator motion respects reduced motion; custom transitions should do the same. Arrow keys, Home and End move selection and skip disabled items. At small widths, horizontal tabs show the selected label, and vertical tabs show icons; accessible names remain available. Each theme demonstration includes fit, fill, vertical, disabled and bound-content examples.
+Material Symbols icons load automatically with Theme. Text uses system fonts, so
+no custom text font installation is required.
+
+The gallery uses the same public package exports at `/themes/vscode`.
 
-These initial themes provide the demo palettes, fonts, common CSS and component styling. They use light mode and document-global Bref tokens/reset styles; mount one theme per document and use full-page navigation when changing themes. Site-specific layouts and content are separate from the library.
+## Community and contributing
 
-## Source layout
+Join [Discord](https://discord.gg/JpgQRTUsVS) and use the `bref-ui` channel for
+questions and examples. Report bugs and suggest themes through
+[GitHub Issues](https://github.com/feuersteiner/bref-ui/issues).
 
-- `src/lib/<theme>/index.ts`: public theme entry; each site's demo and theme demonstration consume it.
-- `src/lib/components`: Bref CLI-copied controls and their local dependencies, with `bref-ui/types` imports preserved.
-- `src/lib/shared`: common reusable theme styling.
-- `src/routes/(sites)`: complete Tasks, House Shop and Site Reviewer sites and the latest shared demo shell.
-- `src/routes/(themes)`: demonstrations of implemented public theme exports.
-- `src/routes/catalog`: showcase content adapted from the reusable gallery.
-- `static/demos`: original photographic assets; `static/previews`: rendered catalog previews. Neither is included in the npm package.
+This package lives in the [Bref-ui monorepo](https://github.com/feuersteiner/bref-ui/tree/main/themes).
+See [CONTRIBUTING.md](https://github.com/feuersteiner/bref-ui/blob/main/CONTRIBUTING.md)
+for contribution guidelines.
 
-The migration preserves the local checkbox motion/reduced-motion fix and animated dialog title/icon updates. Only demo-owned files were extracted from their source branches; the latest Relay shared shell was kept. See [verification.md](verification.md) for source revisions, validation and remaining limitations.
+## License
 
-Tabs was copied from the npm-installed Bref 2.2.0 source using its registry, dependency planner and preview/install pipeline. Existing Icon and Theme dependencies were retained. The preview added only `tabs/tabs.svelte` and `tabs/item.svelte`, with explicit approval for the shared barrel merge; no existing component source was overwritten. Tabs types remain public imports from `bref-ui/types`.
+[MIT](https://github.com/feuersteiner/bref-ui/blob/main/LICENSE).