crayon-design-system-ui 0.0.1

package/README.md

@@ -0,0 +1,487 @@
+# Svelte library
+
+Everything you need to build a Svelte library, powered by [`sv`](https://npmjs.com/package/sv).
+
+Read more about creating a library [in the docs](https://svelte.dev/docs/kit/packaging).
+
+## Creating a project
+
+If you're seeing this, you've probably already done this step. Congrats!
+
+```sh
+# create a new project in the current directory
+npx sv create
+
+# create a new project in my-app
+npx sv create my-app
+```
+
+To recreate this project with the same configuration:
+
+```sh
+# recreate this project
+npx sv create --template library --types ts --no-install design-system-ui
+```
+
+## Developing
+
+Once you've created a project and installed dependencies with `npm install` (or `pnpm install` or `yarn`), start a development server:
+
+```sh
+npm run dev
+
+# or start the server and open the app in a new browser tab
+npm run dev -- --open
+```
+
+Everything inside `src/lib` is part of your library, everything inside `src/routes` can be used as a showcase or preview app.
+
+## Building
+
+To build your library:
+
+```sh
+npm pack
+```
+
+To create a production version of your showcase app:
+
+```sh
+npm run build
+```
+
+You can preview the production build with `npm run preview`.
+
+> To deploy your app, you may need to install an [adapter](https://svelte.dev/docs/kit/adapters) for your target environment.
+
+## Publishing
+
+Go into the `package.json` and give your package the desired name through the `"name"` option. Also consider adding a `"license"` field and point it to a `LICENSE` file which you can create from a template (one popular option is the [MIT license](https://opensource.org/license/mit/)).
+
+To publish your library to [npm](https://www.npmjs.com):
+
+```sh
+npm publish
+```
+
+# Design System UI
+
+Package name: **`crayon-design-system-ui`**. A reusable Design System built using **Svelte 5 + Web Components**, packaged for use in:
+
+- Plain HTML
+- SvelteKit
+- React
+- Angular
+- Vue
+- Any browser-based framework
+
+Use **custom elements** (`import 'crayon-design-system-ui/register'` then `<ui-button>`) everywhere, or in Svelte use the named component: `import { Button } from 'crayon-design-system-ui'`.
+
+Example:
+
+```
+<ui-button></ui-button>
+```
+
+**Component usage docs:** See [docs/README.md](docs/README.md) for a list of per-component usage documents (Button, Accordion, AccordionItem). When you change a component in `src/lib/components/`, update its doc in `docs/components/` so the docs stay in sync.
+
+---
+
+# Architecture Overview
+
+The design system is built using:
+
+- Svelte 5
+- Web Components (customElements)
+- Vite
+- SvelteKit (library mode)
+
+Outputs:
+
+```
+dist/               → Library build (types, Svelte exports)
+dist-browser/      → Browser bundle (registers custom elements)
+```
+
+The browser bundle is the main runtime entry.
+
+---
+
+# Project Structure
+
+```
+design-system-ui/
+
+src/
+  lib/
+    components/
+      Button.svelte
+    index.ts
+
+  register.ts              ← SSR-safe registration entry
+
+vite.config.ts             ← library build config
+vite.browser.config.ts     ← browser bundle config
+
+package.json
+
+
+dist/
+dist-browser/
+```
+
+---
+
+# Component Example
+
+Button component:
+
+```
+<ui-button variant="primary">
+  Click Me
+</ui-button>
+```
+
+Supports:
+
+- variants
+- sizes
+- disabled
+- loading
+- custom color
+- click events
+
+---
+
+# Build Commands
+
+## Build library
+
+```
+npm run build
+```
+
+Output:
+
+```
+dist/
+```
+
+## Build browser bundle
+
+```
+npm run build:browser
+```
+
+Output:
+
+```
+dist-browser/bundle.js
+```
+
+---
+
+# Local npm Packaging
+
+Create installable package:
+
+```
+npm pack
+```
+
+Produces:
+
+```
+design-system-ui-0.0.1.tgz
+```
+
+Install in another project:
+
+```
+npm install ../design-system-ui/design-system-ui-0.0.1.tgz
+```
+
+---
+
+# Usage — Plain HTML
+
+```
+<script type="module">
+  import 'design-system-ui';
+</script>
+
+<ui-button variant="primary">
+  Click Me
+</ui-button>
+```
+
+Optional click event:
+
+```
+document.querySelector('ui-button')
+  .addEventListener('ui-click', () => alert('Clicked'));
+```
+
+Run using local server:
+
+```
+npx serve .
+```
+
+---
+
+# Usage — Same everywhere (Svelte, React, Angular, plain HTML)
+
+Use **custom elements** the same way in every project. You don’t need to know the customer’s framework or Svelte version — one API works everywhere.
+
+**1. Register** (once, e.g. in your app entry or layout):
+
+```js
+import 'crayon-design-system-ui/register';
+```
+
+**2. Use the tags** in your templates/JSX/HTML:
+
+```html
+<ui-button variant="primary">Click Me</ui-button>
+```
+
+**Single component** (smaller bundle): register only what you need:
+
+```js
+import 'crayon-design-system-ui/register/button';
+```
+
+Then use `<ui-button>` as above. Other entries: `register/input`, `register/textarea`, `register/accordion`, `register/accordion-item`, `register/form-select`, `register/form-select-option`, `register/checkbox`, `register/radio`, `register/label`, `register/form`, `register/avatar`, `register/card`.
+
+---
+
+# Usage — Svelte: named component import
+
+In Svelte apps you can also use the **Svelte component** directly (package name: `crayon-design-system-ui`):
+
+```svelte
+<script>
+  import { Button } from 'crayon-design-system-ui';
+</script>
+<Button variant="primary">Click Me</Button>
+```
+
+Other named exports: `Input`, `Textarea`, `Accordion`, `AccordionItem`, `FormSelect`, `FormSelectOption`, `Checkbox`, `Radio`, `Label`, `Form`, `Avatar`, `Card`. Use this when your app and the design system are on the same major Svelte version; otherwise use the custom elements above.
+
+---
+
+# Usage — SvelteKit
+
+## Step 1 — Install
+
+```
+npm install crayon-design-system-ui
+```
+
+(or local .tgz file)
+
+## Step 2 — Register globally
+
+File:
+
+```
+src/routes/+layout.svelte
+```
+
+```svelte
+<script>
+  import 'crayon-design-system-ui/register';
+</script>
+<slot />
+```
+
+For a single component (e.g. only Button):
+
+```svelte
+<script>
+  import 'crayon-design-system-ui/register/button';
+</script>
+<slot />
+```
+
+## Step 3 — Use component
+
+```svelte
+<ui-button variant="primary">
+  Click Me
+</ui-button>
+```
+
+---
+
+# Usage — React / Angular / Other Frameworks
+
+**Option 1 — Named imports (same style as Svelte)**
+
+Register once in your app entry (e.g. `main.tsx` / `main.ts`), then use wrapper components:
+
+**React:**
+
+```ts
+// main.tsx
+import 'crayon-design-system-ui/register';
+
+// In any component:
+import { Button, Input } from 'crayon-design-system-ui/react';
+
+<Button variant="primary">Click</Button>
+<Input placeholder="Name" />
+```
+
+**Angular:**
+
+```ts
+// main.ts
+import 'crayon-design-system-ui/register';
+
+// In a module or standalone component:
+import { CrayonDesignSystemModule } from 'crayon-design-system-ui/angular';
+// or import { ButtonComponent } from 'crayon-design-system-ui/angular';
+
+// Template:
+<crayon-button variant="primary">Click</crayon-button>
+<crayon-input placeholder="Name"></crayon-input>
+```
+
+**Option 2 — Custom elements only**
+
+Register once, then use the custom element tags in templates/JSX:
+
+```ts
+import 'crayon-design-system-ui/register';
+```
+
+```html
+<ui-button variant="primary">Click</ui-button>
+<ui-input placeholder="Name"></ui-input>
+```
+
+---
+
+# SSR-safe Registration
+
+File:
+
+```
+src/register.ts
+```
+
+```
+if (typeof window !== 'undefined' && 'customElements' in window) {
+  import('./lib/components/button/Button.svelte');
+}
+```
+
+Prevents server-side rendering errors.
+
+---
+
+# package.json (important fields)
+
+```
+{
+  "main": "./dist-browser/bundle.js",
+  "types": "./dist/index.d.ts",
+
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist-browser/bundle.js"
+    }
+  },
+
+  "files": [
+    "dist",
+    "dist-browser"
+  ]
+}
+```
+
+Ensures correct runtime entry.
+
+---
+
+# Development
+
+Run dev server:
+
+```
+npm run dev
+```
+
+Build everything:
+
+```
+npm run build
+npm run build:browser
+```
+
+---
+
+# How It Works
+
+When imported:
+
+```
+import 'design-system-ui'
+```
+
+The browser bundle executes:
+
+```
+customElements.define('ui-button', ...)
+```
+
+Registers the component globally.
+
+---
+
+# Supported Environments
+
+Works in:
+
+- Plain HTML
+- SvelteKit
+- React
+- Angular
+- Vue
+- Any browser-based framework
+
+---
+
+# Next Steps
+
+Add more components:
+
+- Input
+- Card
+- Modal
+- Select
+
+Optional:
+
+- Storybook
+- Private npm publish
+- Design tokens
+
+---
+
+# Summary
+
+This design system:
+
+- Uses Web Components
+- Framework independent
+- npm installable
+- SSR-safe
+- Production ready foundation
+
+---
+
+End of README