@ambasada/ui 0.0.0-stage → 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CENTYSO (https://centyso.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,108 @@
-# Temporary Holding Version
+# @ambasada/ui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Ambasada look for mini apps: design tokens (the Ambasada colours, Inter + JetBrains Mono, radii, spacing,
+the mono label, the shell's safe areas and host bar) and a small component set in plain CSS, with optional
+React wrappers. Light only, no framework, no runtime: one stylesheet a plain HTML page can `<link>`.
+
+## Install
+
+```sh
+npm install @ambasada/ui
+```
+
+```ts
+import "@ambasada/ui"; // fonts + tokens + components, once at the root of the app
+```
+
+Or the parts: `@ambasada/ui/tokens.css`, `@ambasada/ui/components.css`, `@ambasada/ui/fonts.css` (skip
+`fonts.css` if you serve Inter and JetBrains Mono yourself).
+
+With no build step, the same three in one file from any npm CDN (the fonts load from next to it):
+
+```html
+<link rel="stylesheet" href="https://unpkg.com/@ambasada/ui@0.5/dist/ambasada-ui.css" />
+```
+
+The `ambasada init` templates load it before their own stylesheet.
+
+## Tokens
+
+All on `:root`, from the Ambasada hub (each has a source comment in `tokens.css`): `--color-accent` (the logo
+red), `--color-accent-text` (red for small text), `--color-bg`, `--color-surface`, `--color-surface-2`,
+`--color-ink` / `-2` / `-3`, `--color-line`, `--color-success` / `warn` / `danger` / `info` and their `-soft`
+tints, `--card-*` (the member card palettes), `--font-sans`, `--font-mono`, `--text-*`, `--weight-*`,
+`--tracking-label`, `--radius-*`, `--shadow-*`, `--space-1` to `--space-10`, `--page-max`, `--tap`, `--ease`,
+`--duration`.
+
+The shell's insets, for anything you position yourself:
+
+| Variable | Default | Inside the Ambasada app |
+|---|---|---|
+| `--ambasada-safe-area-top` / `bottom` / `left` / `right` | `env(safe-area-inset-*, 0px)` | set on `<html>` by `@ambasada/miniapp`'s `ready()` |
+| `--ambasada-host-bar` | `0px` | the height of the shell's top bar |
+
+```css
+.my-bar { position: fixed; bottom: 0; padding-bottom: calc(12px + var(--ambasada-safe-area-bottom, 0px)); }
+```
+
+## Components
+
+| Class | What |
+|---|---|
+| `ui-page` | The 480 px column, padded clear of the host bar and every safe area. |
+| `ui-card`, `ui-card-title` | White card, hairline border, 16 px radius. |
+| `ui-button`, `ui-button secondary`, `block` | Primary (brand red: one per screen) and secondary buttons, ≥ 44 px. On `<button>` or `<a>`. |
+| `ui-label` | The mono label: 11 px, uppercase, 0.1em. Captions, never sentences. |
+| `ui-group` (`ui-group-head`, `ui-group-body`) | A list: rows in one bordered block, with a title. |
+| `ui-row` (`row-icon`, `row-text`, `row-title`, `row-sub`, `row-right`, `row-chev`) | List row; `tappable`, `danger`, `muted`; `row-icon accent` / `good` / `bad`. |
+| `ui-pill` | Status pill with a dot: `good`, `bad`, `warn`, `accent`, `pulse`. |
+| `ui-sheet-backdrop` > `ui-sheet` (`ui-sheet-grip`, `-head`, `-body`, `-foot`), `ui-icon-btn` | Bottom sheet; a centred dialog from 640 px. Add `ui-sheet-open` to `<body>` while open. |
+| `ui-stepper-wrap` > `ui-stepper` (`ui-stepper-value`), `ui-presets` | − value + for amounts, with preset chips (`on`). |
+| `ui-empty` (`ui-empty-icon`) | Empty state: icon, `<strong>` title, hint, action. |
+| `ui-skeleton` | Grey bars (`<span>`s) while loading: skeletons, not spinners. |
+
+```html
+<main class="ui-page">
+  <p class="ui-label">// My Company</p>
+  <section class="ui-card">
+    <h2 class="ui-card-title">Your name as a folk poem</h2>
+    <button class="ui-button block">Pay 2 TON</button>
+  </section>
+  <section class="ui-group">
+    <div class="ui-group-head"><h2>Orders</h2></div>
+    <div class="ui-group-body">
+      <a class="ui-row tappable" href="/orders/1">
+        <span class="row-text"><span class="row-title">Poem for Ana</span><span class="row-sub">2 min ago</span></span>
+        <span class="row-right"><span class="ui-pill good"><i></i>Ready</span></span>
+      </a>
+    </div>
+  </section>
+</main>
+```
+
+## React
+
+```tsx
+import { Button, Card, Empty, Group, Page, Pill, Row, Sheet, Skeleton, Stepper } from "@ambasada/ui/react";
+
+<Page>
+  <Card title="Your name as a folk poem">
+    <Button block onClick={() => setOpen(true)}>Pay 2 TON</Button>
+  </Card>
+  <Group title="Orders">
+    <Row title="Poem for Ana" sub="2 min ago" right={<Pill tone="good">Ready</Pill>} href="/orders/1" />
+  </Group>
+  <Sheet open={open} onClose={() => setOpen(false)} title="Pay" footer={<Button>Pay 2 TON</Button>}>
+    <Stepper value={amount} onChange={setAmount} min={1} unit="TON" presets={[1, 2, 5]} />
+  </Sheet>
+</Page>
+```
+
+The wrappers render markup only and import no CSS (load the stylesheet yourself). The module is marked
+`"use client"` (`Sheet` uses effects), so Next.js server components can render them too; they server-render
+with `react-dom/server`. React ≥ 18 is an optional peer dependency.
+
+Rules for the look (one red thing per screen, light only, sheets for forms): docs/DESIGN-SYSTEM.md and
+docs/MINI-APPS.md §9 in the Ambasada repo.
+
+MIT, © CENTYSO. Inter and JetBrains Mono: SIL Open Font License 1.1 (`fonts/OFL-*.txt`).