@tanishqkancharla/maui 0.0.34 → 0.0.35
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json
CHANGED
package/skills/maui/SKILL.md
CHANGED
|
@@ -1,157 +1,59 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: maui
|
|
3
|
-
description: Conventions
|
|
3
|
+
description: Conventions for installing, updating, and consuming the Maui design system. Use when changing the Maui package or building UI with Maui tokens, components, patterns, or purse-styles.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Maui
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
Read the reference for the work you are doing:
|
|
9
9
|
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
import {
|
|
13
|
-
MauiProvider,
|
|
14
|
-
background,
|
|
15
|
-
border,
|
|
16
|
-
colors,
|
|
17
|
-
radius,
|
|
18
|
-
shadow,
|
|
19
|
-
} from "maui"
|
|
10
|
+
- When installing or updating the Maui package, read [installing_maui.md](references/installing_maui.md).
|
|
11
|
+
- When designing, implementing, or reviewing UI with Maui, read [design_conventions.md](references/design_conventions.md), then open every matching component, pattern, or app reference below.
|
|
20
12
|
|
|
21
|
-
|
|
22
|
-
return (
|
|
23
|
-
<MauiProvider>
|
|
24
|
-
{/* … */}
|
|
25
|
-
</MauiProvider>
|
|
26
|
-
)
|
|
27
|
-
}
|
|
28
|
-
```
|
|
13
|
+
## Foundation
|
|
29
14
|
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
- `"maui/icons"` — tree-shakeable named icon modules (same names as `Icons.*`)
|
|
34
|
-
- `"maui/src"` — TypeScript source barrel
|
|
35
|
-
- `"maui/src/*"` — TypeScript source for deep imports
|
|
36
|
-
- `"maui/skills/maui"` — this skill file
|
|
37
|
-
- `"maui/skills/maui/*"` — reference files next to this skill
|
|
38
|
-
|
|
39
|
-
`MauiProvider` sets up theme (`data-theme` / `color-scheme`), `PurseProvider`, design-system globals, and the focus UI database used by Button/Dialog.
|
|
40
|
-
|
|
41
|
-
## How to learn Maui
|
|
42
|
-
|
|
43
|
-
Prefer this skill for composition knowledge — how to assemble tokens, components, patterns, and apps. Reach for package source (`"maui/src/patterns"`, `"maui/src/apps"`, or an install under `node_modules`) when you need a detail the skill does not cover.
|
|
44
|
-
|
|
45
|
-
Before designing or implementing new UI:
|
|
46
|
-
|
|
47
|
-
1. Read the constraints in this file.
|
|
48
|
-
2. Open the matching reference (same grouping as the [gallery nav](https://maui.tanishqkancharla.dev)) and reuse its structure, tokens, and interactions.
|
|
49
|
-
|
|
50
|
-
| Need | Read |
|
|
51
|
-
| --- | --- |
|
|
52
|
-
| Tokens, `purse-styles`, motion, layout, theme | [references/tokens.md](references/tokens.md) |
|
|
53
|
-
| A component | [Components](#components) |
|
|
54
|
-
| A pattern | [Patterns](#patterns) |
|
|
55
|
-
| An app | [Apps](#apps) |
|
|
56
|
-
|
|
57
|
-
Patterns, demo apps, and the gallery `Panel` preview frame are **not** package components. `Panel` is not on the `"maui"` barrel, not in `src/components`, and not in the JSX editor catalog. Prefer the recipes in those references and rebuild with barrel exports (`Button`, `Flex`, `text(...)`, …).
|
|
58
|
-
|
|
59
|
-
## Design constraints
|
|
60
|
-
|
|
61
|
-
- Hover backgrounds have no transitions. Hover fills (`backgroundColor.elementHover`, quiet-button washes, list/row highlights) snap instantly. Do not animate `background` / `background-color` on hover with `motion.standard(...)` or a CSS `transition`. Other motion (tooltips, transforms) is fine.
|
|
62
|
-
- Simple apps default to a `proseMaxWidth` column (`72ch`) centered in their container: `width: "100%"`, `maxWidth: proseMaxWidth`, `marginInline: "auto"`. `sizing.contentWidth` is the same measure. Use this for single-column tools, settings, forms, and reading layouts. Multi-pane or full-bleed apps (inbox, calendar, IDE) are the exception.
|
|
63
|
-
- Always design empty states. Every list, inbox, search result, or collection needs an intentional empty composition (copy and an optional action), never a blank panel.
|
|
64
|
-
|
|
65
|
-
## Theme FOUC
|
|
66
|
-
|
|
67
|
-
Put the exported `themeFoucScript` string in a classic inline `<script>` in `<head>` (before React boots) so `data-theme` is correct on first paint. The gallery `src/index.html` uses the same script.
|
|
68
|
-
|
|
69
|
-
Use `useTheme()` for preference / resolved theme. Token dark values use the `DARK_THEME` selector (`:root[data-theme="dark"]`). Prefer semantic tokens (`colors`, `background`, `avatar`, `focusRing()`) over bespoke CSS variables.
|
|
70
|
-
|
|
71
|
-
## Shadows
|
|
72
|
-
|
|
73
|
-
Use the three-level elevation scale:
|
|
74
|
-
|
|
75
|
-
- `shadow.subtle` — controls, cards, and ordinary raised surfaces
|
|
76
|
-
- `shadow.medium` — tooltips and larger floating panels
|
|
77
|
-
- `shadow.strong` — dropdowns, popovers, and dominant overlays
|
|
78
|
-
|
|
79
|
-
All three already include a 1px ring. Do not also apply `border()`, `borderColor.outline`, or another ring on the same element.
|
|
80
|
-
|
|
81
|
-
Buttons and form-control surfaces use `shadow.subtle` by default. For compound
|
|
82
|
-
controls, apply it once to the outer control boundary rather than to every
|
|
83
|
-
internal button or segment.
|
|
84
|
-
|
|
85
|
-
## Focus
|
|
86
|
-
|
|
87
|
-
`focusRing()` applies a theme-aware Radix blue shadow (`blueAlpha[8]` hard edge + `blueAlpha[5]` glow). Do not hand-roll a competing outline or box-shadow for keyboard focus.
|
|
88
|
-
|
|
89
|
-
## Layout utilities
|
|
90
|
-
|
|
91
|
-
`Flex` and `Gap` take spacing scale steps (`1 | 2 | 3 | 4 | 6 | 8 | 12 | 16`), not raw pixels. Example: `<Flex row gap={4} padding={4}>` is 9px gap and 9px inset, not 4px. Put padding on `Flex` (`padding` / `p`, `px`, `py`, `pt`, `pr`, `pb`, `pl`) — there is no `Padding` component. `alignItems` and `justifyContent` use the same tokens as `flex()` (`start` | `center` | `end` | …; `justifyContent` also has `between` | `around` | `evenly`). `background` is a surface token (`app`, `element`, `accent`, …). `Spacer` grows to fill leftover flex space. `Divider` is a horizontal rule.
|
|
92
|
-
|
|
93
|
-
## Icons
|
|
94
|
-
|
|
95
|
-
Import named icons so unused SVGs are tree-shaken. Do not import the `Icons` namespace in app code unless you want the full set.
|
|
96
|
-
|
|
97
|
-
```ts
|
|
98
|
-
import { Search, Plus } from "maui"
|
|
99
|
-
import { Text as TextIcon } from "maui/icons"
|
|
100
|
-
|
|
101
|
-
<Search size="sm" />
|
|
102
|
-
<TextIcon size="md" />
|
|
103
|
-
```
|
|
104
|
-
|
|
105
|
-
`size` uses the same t-shirt scale as `text(...)` (`2xs`–`xl`, default `sm`). Stroke and fill use `currentColor`. Icons that share a root export name (`Text`, `Badge`, `Switch`, `H1`, `H2`, `H3`, `Link`, `Menu`, `Code`, `Blockquote`, `Padding`, `SearchField`) are `TextIcon` / `BadgeIcon` / … from `"maui"`, or the original name from `"maui/icons"` / `Icons.Text`.
|
|
15
|
+
| Need | Reference |
|
|
16
|
+
| --------------------------------------------- | --------------------------------- |
|
|
17
|
+
| Tokens, `purse-styles`, motion, layout, theme | [tokens.md](references/tokens.md) |
|
|
106
18
|
|
|
107
19
|
## Components
|
|
108
20
|
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
|
112
|
-
|
|
|
113
|
-
|
|
|
114
|
-
|
|
|
115
|
-
|
|
|
116
|
-
|
|
|
117
|
-
|
|
|
118
|
-
|
|
|
119
|
-
|
|
|
120
|
-
|
|
|
121
|
-
|
|
|
122
|
-
|
|
|
123
|
-
|
|
|
124
|
-
|
|
|
125
|
-
|
|
|
126
|
-
|
|
|
127
|
-
|
|
|
128
|
-
|
|
|
129
|
-
|
|
|
130
|
-
|
|
|
131
|
-
| Icons | [icons.md](references/components/icons.md) |
|
|
132
|
-
| Code | [code.md](references/components/code.md) |
|
|
21
|
+
| Page | Reference |
|
|
22
|
+
| ---------------- | -------------------------------------------------------------------------------------------- |
|
|
23
|
+
| Avatar | [avatar.md](references/components/avatar.md) |
|
|
24
|
+
| Badge | [badge.md](references/components/badge.md) |
|
|
25
|
+
| Buttons | [buttons.md](references/components/buttons.md) (`Button`, `Overlay`, `Dialog`) |
|
|
26
|
+
| Drawer | [drawer.md](references/components/drawer.md) |
|
|
27
|
+
| Prose | [prose.md](references/components/prose.md) (`Prose`, `H1`–`H4`, `P`, lists, `Label`, `Link`) |
|
|
28
|
+
| Editor | [editor.md](references/components/editor.md) |
|
|
29
|
+
| Thinking | [thinking.md](references/components/thinking.md) |
|
|
30
|
+
| Crossfade | [crossfade.md](references/components/crossfade.md) |
|
|
31
|
+
| Loading screen | [loading-screen.md](references/components/loading-screen.md) |
|
|
32
|
+
| Text | [text.md](references/components/text.md) |
|
|
33
|
+
| Form controls | [form-controls.md](references/components/form-controls.md) |
|
|
34
|
+
| Select | [select.md](references/components/select.md) |
|
|
35
|
+
| List box | [list-box.md](references/components/list-box.md) |
|
|
36
|
+
| Table | [table.md](references/components/table.md) |
|
|
37
|
+
| Menu | [menu.md](references/components/menu.md) |
|
|
38
|
+
| Tooltip | [tooltip.md](references/components/tooltip.md) |
|
|
39
|
+
| Layout utilities | [layout-utilities.md](references/components/layout-utilities.md) |
|
|
40
|
+
| FuzzyString | [fuzzy-string.md](references/components/fuzzy-string.md) |
|
|
41
|
+
| Icons | [icons.md](references/components/icons.md) |
|
|
42
|
+
| Code | [code.md](references/components/code.md) |
|
|
133
43
|
|
|
134
44
|
## Patterns
|
|
135
45
|
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
|
139
|
-
|
|
|
140
|
-
|
|
|
141
|
-
|
|
|
142
|
-
| Assistant message | Streaming markdown reply (Streamdown + Maui prose + CodeBlock) | [assistant-message.md](references/patterns/assistant-message.md) |
|
|
143
|
-
| Sidebar | 240px nav: sections, active item, optional icon and trailing badge | [sidebar.md](references/patterns/sidebar.md) |
|
|
46
|
+
| Page | Role | Reference |
|
|
47
|
+
| ----------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------- |
|
|
48
|
+
| Inbox | Mail thread list with unread dot, hover actions, selection | [inbox.md](references/patterns/inbox.md) |
|
|
49
|
+
| Message list | Thread of raised message cards (avatar + Prose body) | [message-list.md](references/patterns/message-list.md) |
|
|
50
|
+
| Assistant message | Streaming markdown reply (Streamdown + Maui prose + CodeBlock) | [assistant-message.md](references/patterns/assistant-message.md) |
|
|
51
|
+
| Sidebar | 240px nav: sections, active item, optional icon and trailing badge | [sidebar.md](references/patterns/sidebar.md) |
|
|
144
52
|
|
|
145
53
|
## Apps
|
|
146
54
|
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
|
150
|
-
|
|
|
151
|
-
|
|
|
152
|
-
| AI chat | Mock streaming chat (Editor + AssistantMessage + Thinking) | [ai-chat.md](references/apps/ai-chat.md) |
|
|
153
|
-
| Calendar | Three-pane schedule (mini month, week grid, event details) | [calendar.md](references/apps/calendar.md) |
|
|
154
|
-
|
|
155
|
-
## License
|
|
156
|
-
|
|
157
|
-
Maui is open source under the MIT License.
|
|
55
|
+
| Page | Role | Reference |
|
|
56
|
+
| ------------ | ---------------------------------------------------------- | -------------------------------------------------- |
|
|
57
|
+
| Calendar | Three-pane schedule (mini month, week grid, event details) | [calendar.md](references/apps/calendar.md) |
|
|
58
|
+
| Email client | Two-pane inbox + reading pane | [email-client.md](references/apps/email-client.md) |
|
|
59
|
+
| AI chat | Mock streaming chat (Editor + AssistantMessage + Thinking) | [ai-chat.md](references/apps/ai-chat.md) |
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
# Maui design conventions
|
|
2
|
+
|
|
3
|
+
Prefer the Maui skill for composition knowledge: how to assemble tokens, components, patterns, and apps. Read every matching reference linked from `SKILL.md` before designing or implementing UI, and reuse its structure, tokens, and interactions. Reach for package source under `"maui/src/patterns"`, `"maui/src/apps"`, or an installed `node_modules` package only when the references do not cover a needed detail.
|
|
4
|
+
|
|
5
|
+
Patterns, demo apps, and the gallery `Panel` preview frame are not package components. `Panel` is not on the `"maui"` barrel, in `src/components`, or in the JSX editor catalog. Rebuild reference recipes with barrel exports such as `Button`, `Flex`, and `text(...)`.
|
|
6
|
+
|
|
7
|
+
## Composition
|
|
8
|
+
|
|
9
|
+
- Hover backgrounds have no transitions. Hover fills such as `backgroundColor.elementHover`, quiet-button washes, and list or row highlights snap instantly. Do not animate `background` or `background-color` on hover with `motion.standard(...)` or a CSS `transition`. Other motion, including tooltips and transforms, is allowed.
|
|
10
|
+
- Simple apps default to a `proseMaxWidth` column (`72ch`) centered in their container with `width: "100%"`, `maxWidth: proseMaxWidth`, and `marginInline: "auto"`. `sizing.contentWidth` is the same measure. Use it for single-column tools, settings, forms, and reading layouts. Multi-pane or full-bleed apps such as inboxes, calendars, and IDEs are exceptions.
|
|
11
|
+
- Design an intentional empty composition for every list, inbox, search result, or collection. Include copy and, when useful, an action. Do not leave a blank panel.
|
|
12
|
+
|
|
13
|
+
## Shadows
|
|
14
|
+
|
|
15
|
+
Use the three-level elevation scale:
|
|
16
|
+
|
|
17
|
+
- `shadow.subtle` — controls, cards, and ordinary raised surfaces
|
|
18
|
+
- `shadow.medium` — tooltips and larger floating panels
|
|
19
|
+
- `shadow.strong` — dropdowns, popovers, and dominant overlays
|
|
20
|
+
|
|
21
|
+
All three include a 1px ring. Do not also apply `border()`, `borderColor.outline`, or another ring to the same element.
|
|
22
|
+
|
|
23
|
+
Buttons and form-control surfaces use `shadow.subtle` by default. For compound controls, apply it once to the outer control boundary instead of to every internal button or segment.
|
|
24
|
+
|
|
25
|
+
## Focus
|
|
26
|
+
|
|
27
|
+
`focusRing()` applies a theme-aware Radix blue shadow with a `blueAlpha[8]` hard edge and `blueAlpha[5]` glow. Do not add a competing outline or box shadow for keyboard focus.
|
|
28
|
+
|
|
29
|
+
## Layout utilities
|
|
30
|
+
|
|
31
|
+
`Flex` and `Gap` take spacing scale steps (`1 | 2 | 3 | 4 | 6 | 8 | 12 | 16`), not raw pixels. For example, `<Flex row gap={4} padding={4}>` has a 9px gap and 9px inset.
|
|
32
|
+
|
|
33
|
+
Put padding on `Flex` with `padding` or `p`, `px`, `py`, `pt`, `pr`, `pb`, and `pl`; there is no `Padding` component. `alignItems` and `justifyContent` use the same tokens as `flex()` (`start`, `center`, `end`, and others; `justifyContent` also supports `between`, `around`, and `evenly`). `background` is a surface token such as `app`, `element`, or `accent`. `Spacer` grows to fill leftover flex space. `Divider` is a horizontal rule.
|
|
34
|
+
|
|
35
|
+
## Icons
|
|
36
|
+
|
|
37
|
+
Import named icons so unused SVGs are tree-shaken. Import the `Icons` namespace only when the app needs the full set.
|
|
38
|
+
|
|
39
|
+
```ts
|
|
40
|
+
import { Search, Plus } from "maui"
|
|
41
|
+
import { Text as TextIcon } from "maui/icons"
|
|
42
|
+
|
|
43
|
+
<Search size="sm" />
|
|
44
|
+
<TextIcon size="md" />
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
`size` uses the same t-shirt scale as `text(...)` (`2xs`–`xl`, default `sm`). Stroke and fill use `currentColor`. Icons whose root export names collide with components (`Text`, `Badge`, `Switch`, `H1`, `H2`, `H3`, `Link`, `Menu`, `Code`, `Blockquote`, `Padding`, `SearchField`) use names such as `TextIcon` and `BadgeIcon` from `"maui"`, or their original names from `"maui/icons"` or `Icons.Text`.
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
# Installing and updating Maui
|
|
2
|
+
|
|
3
|
+
Maui is a TypeScript-first design system styled with `purse-styles`. Wrap the app in `MauiProvider`, then import tokens and components from `"maui"`.
|
|
4
|
+
|
|
5
|
+
```ts
|
|
6
|
+
import { style } from "purse-styles"
|
|
7
|
+
import {
|
|
8
|
+
MauiProvider,
|
|
9
|
+
background,
|
|
10
|
+
border,
|
|
11
|
+
colors,
|
|
12
|
+
radius,
|
|
13
|
+
shadow,
|
|
14
|
+
} from "maui"
|
|
15
|
+
|
|
16
|
+
function App() {
|
|
17
|
+
return (
|
|
18
|
+
<MauiProvider>
|
|
19
|
+
{/* … */}
|
|
20
|
+
</MauiProvider>
|
|
21
|
+
)
|
|
22
|
+
}
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
The published package exposes:
|
|
26
|
+
|
|
27
|
+
- `"maui"` — compiled barrel (`dist/`) of provider, theme, tokens, and components
|
|
28
|
+
- `"maui/icons"` — tree-shakeable named icon modules using the same names as `Icons.*`
|
|
29
|
+
- `"maui/src"` — TypeScript source barrel
|
|
30
|
+
- `"maui/src/*"` — TypeScript source for deep imports
|
|
31
|
+
- `"maui/skills/maui"` — the Maui skill entrypoint
|
|
32
|
+
- `"maui/skills/maui/*"` — reference files next to the skill
|
|
33
|
+
|
|
34
|
+
`MauiProvider` sets up the theme (`data-theme` and `color-scheme`), `PurseProvider`, design-system globals, and the focus UI database used by Button and Dialog.
|
|
35
|
+
|
|
36
|
+
## Theme initialization
|
|
37
|
+
|
|
38
|
+
Put the exported `themeFoucScript` string in a classic inline `<script>` in `<head>` before React starts so `data-theme` is correct on first paint. The gallery `src/index.html` uses the same script.
|
|
39
|
+
|
|
40
|
+
Use `useTheme()` for the preference and resolved theme. Token dark values use the `DARK_THEME` selector (`:root[data-theme="dark"]`). Prefer semantic tokens such as `colors`, `background`, `avatar`, and `focusRing()` over bespoke CSS variables.
|
|
41
|
+
|
|
42
|
+
Maui is open source under the MIT License.
|