admin-ui-starter-kit 0.1.0

package/.agents/skills/component-library-rules/references/components/base__typography.md

@@ -0,0 +1,277 @@
+---
+id: base/typography
+title: "Typography"
+description: "Heading, Text, Label, and TextLink — the four typography primitives every higher layer composes from."
+layer: base
+family: "Foundations"
+sourcePath: src/components/typography
+examples:
+  - HeadingTags
+  - HeadingWithSubHeading
+  - TextSizes
+  - TextTypes
+  - TextWeights
+  - TextLineHeights
+  - TextAlignment
+  - TextContentAndHTML
+  - TextTags
+  - LabelExample
+  - TextLinkVariants
+  - TextLinkSizes
+  - HighLightExample
+  - UnderlineExample
+  - DangerousHTMLExample
+  - RealisticArticle
+imports:
+  - @/components/typography/heading
+  - @/components/typography/label
+  - @/components/typography/text
+  - @/components/typography/text-link
+  - @/components/typography/typography
+tags:
+  - base
+  - foundations
+  - typography
+  - heading
+  - text
+  - label
+  - textlink
+---
+
+# Typography
+
+Heading, Text, Label, and TextLink — the four typography primitives every higher layer composes from.
+
+**Layer:** `base`  
+**Source:** `src/components/typography`
+
+## Examples
+
+```tsx
+import Heading from '@/components/typography/heading';
+import { Text } from '@/components/typography/text';
+import Label from '@/components/typography/label';
+import TextLink from '@/components/typography/text-link';
+import { HighLight, Underline, DangerousHTML } from '@/components/typography/typography';
+
+const SIZES = ['xxs', 'xs', 'sm', 'base', 'lg', 'xl'] as const;
+const TYPES = ['main', 'inverse', 'secondary', 'discrete', 'error', 'success', 'primary'] as const;
+const WEIGHTS = ['regular', 'medium', 'semibold', 'bold'] as const;
+const LINE_HEIGHTS = ['none', 'tight', 'snug', 'normal', 'relaxed', 'loose'] as const;
+
+export function HeadingTags() {
+	return (
+		<div className="flex flex-col gap-3 w-full">
+			{(['h1', 'h2', 'h3', 'h4', 'h5', 'h6'] as const).map((tag) => (
+				<Heading key={tag} tag={tag}>{tag.toUpperCase()} — The quick brown fox</Heading>
+			))}
+		</div>
+	);
+}
+
+export function HeadingWithSubHeading() {
+	return (
+		<div className="flex flex-col gap-6 w-full">
+			<Heading tag="h2" subHeading="A short supporting line beneath the heading.">
+				Section title
+			</Heading>
+			<Heading tag="h3" subHeading="Centered subheading." align="center">
+				Centered
+			</Heading>
+			<Heading tag="h3" subHeading="Right-aligned subheading." align="right">
+				Right
+			</Heading>
+		</div>
+	);
+}
+
+export function TextSizes() {
+	return (
+		<div className="flex flex-col gap-2 w-full">
+			{SIZES.map((size) => (
+				<Text key={size} size={size}>
+					{size}: The quick brown fox jumps over the lazy dog.
+				</Text>
+			))}
+		</div>
+	);
+}
+
+export function TextTypes() {
+	return (
+		<div className="flex flex-col gap-2 w-full">
+			{TYPES.filter((t) => t !== 'inverse').map((type) => (
+				<Text key={type} type={type}>
+					type=&quot;{type}&quot; — sample text
+				</Text>
+			))}
+			<div className="rounded-md bg-foreground p-3">
+				<Text type="inverse">type=&quot;inverse&quot; — on dark background</Text>
+			</div>
+		</div>
+	);
+}
+
+export function TextWeights() {
+	return (
+		<div className="flex flex-col gap-2 w-full">
+			{WEIGHTS.map((w) => (
+				<Text key={w} weight={w}>weight={w} — sample text</Text>
+			))}
+		</div>
+	);
+}
+
+export function TextLineHeights() {
+	return (
+		<div className="flex flex-col gap-3 w-full">
+			{LINE_HEIGHTS.map((lh) => (
+				<div key={lh} className="rounded border border-dashed border-border p-2">
+					<Text lineHeight={lh}>
+						lineHeight=&quot;{lh}&quot; — Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+						Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+					</Text>
+				</div>
+			))}
+		</div>
+	);
+}
+
+export function TextAlignment() {
+	return (
+		<div className="flex flex-col gap-2 w-full">
+			<Text align="left">Left aligned text</Text>
+			<Text align="center">Center aligned text</Text>
+			<Text align="right">Right aligned text</Text>
+		</div>
+	);
+}
+
+export function TextContentAndHTML() {
+	return (
+		<div className="flex flex-col gap-2 w-full">
+			<Text content="Rendered via the content prop" />
+			<Text asHTML content="<strong>Sanitised</strong> HTML — &lt;script&gt;alert(1)&lt;/script&gt; is stripped." />
+		</div>
+	);
+}
+
+export function TextTags() {
+	return (
+		<div className="flex flex-col gap-2 w-full">
+			<Text tag="p">tag=&quot;p&quot; (default)</Text>
+			<Text tag="div">tag=&quot;div&quot;</Text>
+			<Text tag="span">tag=&quot;span&quot; — flows inline</Text>
+		</div>
+	);
+}
+
+export function LabelExample() {
+	return (
+		<div className="flex flex-col gap-3 w-full max-w-sm">
+			<div className="space-y-1">
+				<Label>Email address</Label>
+				<input className="w-full rounded border border-border bg-background px-2 py-1.5 text-sm" placeholder="you@example.com" />
+			</div>
+			<div className="space-y-1">
+				<Label className="text-primary">Custom-coloured label</Label>
+				<input className="w-full rounded border border-border bg-background px-2 py-1.5 text-sm" />
+			</div>
+		</div>
+	);
+}
+
+export function TextLinkVariants() {
+	return (
+		<div className="flex flex-col gap-2 w-full">
+			<TextLink href="#">Default link</TextLink>
+			<TextLink href="#" underline={false}>Without underline</TextLink>
+			<TextLink href="#" type="primary" weight="semibold">Primary semibold</TextLink>
+			<TextLink href="#" type="error">Destructive link</TextLink>
+			<TextLink href="#" type="success">Success link</TextLink>
+		</div>
+	);
+}
+
+export function TextLinkSizes() {
+	return (
+		<div className="flex flex-wrap items-baseline gap-4 w-full">
+			<TextLink href="#" size="xs">xs</TextLink>
+			<TextLink href="#" size="sm">sm</TextLink>
+			<TextLink href="#" size="base">base</TextLink>
+			<TextLink href="#" size="lg">lg</TextLink>
+			<TextLink href="#" size="xl">xl</TextLink>
+		</div>
+	);
+}
+
+export function HighLightExample() {
+	return (
+		<div className="flex flex-col gap-2">
+			<Text>Default <HighLight content="primary" /> highlighted text</Text>
+			<Text>Variant <HighLight content="success" variant="success" /> highlight</Text>
+			<Text>Variant <HighLight content="warning" variant="warning" /> highlight</Text>
+			<Text>Variant <HighLight content="error" variant="error" /> highlight</Text>
+		</div>
+	);
+}
+
+export function UnderlineExample() {
+	return (
+		<div className="flex flex-col gap-2">
+			<Text><Underline content="primary underline" /></Text>
+			<Text><Underline content="success underline" variant="success" /></Text>
+			<Text><Underline content="warning underline" variant="warning" /></Text>
+			<Text><Underline content="error underline" variant="error" /></Text>
+		</div>
+	);
+}
+
+export function DangerousHTMLExample() {
+	return (
+		<div className="w-full max-w-md">
+			<DangerousHTML>{'<strong>Sanitised</strong> HTML — &lt;script&gt;alert(1)&lt;/script&gt; tags are stripped before render.'}</DangerousHTML>
+		</div>
+	);
+}
+
+export function RealisticArticle() {
+	return (
+		<article className="w-full max-w-2xl space-y-4">
+			<Heading tag="h1" subHeading="Published 3 May 2026 by Sarah Smitha">
+				Designing for clarity at scale
+			</Heading>
+			<Text size="base" lineHeight="relaxed">
+				When the product surface grows past a single screen, every label, every
+				caption, and every empty state has to pull double duty. Hierarchy stops
+				being a nice-to-have — it becomes the whole point.
+			</Text>
+			<Heading tag="h2">The three rules</Heading>
+			<Text lineHeight="relaxed">
+				One typeface. One scale. One weight per role.
+				<TextLink href="#" type="primary" className="ml-1">Read the full essay</TextLink>.
+			</Text>
+		</article>
+	);
+}
+```
+
+## Example exports
+
+- `HeadingTags`
+- `HeadingWithSubHeading`
+- `TextSizes`
+- `TextTypes`
+- `TextWeights`
+- `TextLineHeights`
+- `TextAlignment`
+- `TextContentAndHTML`
+- `TextTags`
+- `LabelExample`
+- `TextLinkVariants`
+- `TextLinkSizes`
+- `HighLightExample`
+- `UnderlineExample`
+- `DangerousHTMLExample`
+- `RealisticArticle`
+

package/.agents/skills/component-library-rules/references/components/base__upload-tray.md

@@ -0,0 +1,180 @@
+---
+id: base/upload-tray
+title: "Upload tray"
+description: "Drag-drop area + per-file progress rows + summary toolbar. Composes Dropzone and UploadProgressList. Framework-agnostic — the consumer drives the actual transfer."
+layer: base
+family: "Forms & inputs"
+sourcePath: src/components/base/forms/fields
+examples:
+  - Default
+  - EmptyDropzoneOnly
+  - MixedItemStates
+  - LiveSimulatedUpload
+  - LocalisedFrench
+imports:
+  - @/components/base/forms/fields
+tags:
+  - base
+  - forms
+  - inputs
+  - fields
+  - upload
+  - tray
+  - drag
+  - drop
+---
+
+# Upload tray
+
+Drag-drop area + per-file progress rows + summary toolbar. Composes Dropzone and UploadProgressList. Framework-agnostic — the consumer drives the actual transfer.
+
+**Layer:** `base`  
+**Source:** `src/components/base/forms/fields`
+
+## Examples
+
+```tsx
+import { useCallback, useState } from 'react';
+import {
+	UploadTray,
+	type UploadItem,
+} from '@/components/base/forms/fields';
+
+function formatBytes(bytes: number): string {
+	if (bytes < 1024) return `${bytes} B`;
+	if (bytes < 1024 ** 2) return `${(bytes / 1024).toFixed(1)} KB`;
+	if (bytes < 1024 ** 3) return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+	return `${(bytes / 1024 / 1024 / 1024).toFixed(1)} GB`;
+}
+
+const INITIAL: UploadItem[] = [
+	{ id: 'seed-1', name: 'spec.pdf', size: '420 KB', status: 'done', progress: 100 },
+	{ id: 'seed-2', name: 'photo-large.png', size: '2.4 MB', status: 'error', progress: 65, error: 'Upload failed. Please try again.' },
+	{ id: 'seed-3', name: 'archive.zip', size: '8.1 MB', status: 'uploading', progress: 42 },
+];
+
+export function Default() {
+	const [items, setItems] = useState<UploadItem[]>([]);
+	const onAddFiles = useCallback((files: File[]) => {
+		const next: UploadItem[] = files.map((f) => ({
+			id: `${Date.now()}-${f.name}`,
+			name: f.name,
+			size: formatBytes(f.size),
+			progress: 0,
+			status: 'uploading' as const,
+		}));
+		setItems((prev) => [...prev, ...next]);
+	}, []);
+	return (
+		<div className="w-full max-w-2xl">
+			<UploadTray items={items} onAddFiles={onAddFiles} />
+		</div>
+	);
+}
+
+export function EmptyDropzoneOnly() {
+	return (
+		<div className="w-full max-w-2xl">
+			<UploadTray items={[]} onAddFiles={() => {}} />
+		</div>
+	);
+}
+
+export function MixedItemStates() {
+	const [items, setItems] = useState<UploadItem[]>(INITIAL);
+	return (
+		<div className="w-full max-w-2xl">
+			<UploadTray
+				items={items}
+				onAddFiles={() => {}}
+				onRetry={(id) =>
+					setItems((prev) =>
+						prev.map((it) => (it.id === id ? { ...it, status: 'uploading', progress: 0, error: undefined } : it)),
+					)
+				}
+				onRemove={(id) => setItems((prev) => prev.filter((it) => it.id !== id))}
+				onClearAll={() => setItems([])}
+			/>
+		</div>
+	);
+}
+
+export function LiveSimulatedUpload() {
+	const [items, setItems] = useState<UploadItem[]>([]);
+	const onAddFiles = useCallback((files: File[]) => {
+		const next: UploadItem[] = files.map((f) => ({
+			id: `${Date.now()}-${f.name}`,
+			name: f.name,
+			size: formatBytes(f.size),
+			progress: 0,
+			status: 'uploading' as const,
+		}));
+		setItems((prev) => [...prev, ...next]);
+	}, []);
+	return (
+		<div className="w-full max-w-2xl">
+			<UploadTray
+				items={items}
+				onAddFiles={onAddFiles}
+				onRemove={(id) => setItems((prev) => prev.filter((it) => it.id !== id))}
+				onClearAll={items.length > 0 ? () => setItems([]) : undefined}
+				dropzone={{
+					multiple: true,
+					strings: {
+						instruction: 'Drag files here or click to browse',
+						helper: 'Up to 10 MB each — images, PDFs, archives',
+					},
+				}}
+			/>
+		</div>
+	);
+}
+
+export function LocalisedFrench() {
+	return (
+		<div className="w-full max-w-2xl">
+			<UploadTray
+				items={INITIAL.slice(0, 2)}
+				onAddFiles={() => {}}
+				onRetry={() => {}}
+				onRemove={() => {}}
+				onClearAll={() => {}}
+				strings={{
+					heading: 'Téléversements',
+					completedLabel: 'Terminés',
+					failedLabel: 'Échoués',
+					uploadingLabel: 'En cours',
+					queuedLabel: 'En attente',
+					clearAll: 'Tout effacer',
+				}}
+				listStrings={{
+					queued: 'En attente',
+					uploading: 'En cours',
+					done: 'Terminé',
+					error: 'Échoué',
+					cancelled: 'Annulé',
+					cancel: 'Annuler',
+					retry: 'Réessayer',
+					remove: 'Supprimer',
+				}}
+				dropzone={{
+					strings: {
+						instruction: 'Glissez vos fichiers ou cliquez',
+						helper: 'PDF, images, archives — 10 Mo maximum',
+						dragOver: 'Relâchez pour téléverser',
+					},
+				}}
+			/>
+		</div>
+	);
+}
+```
+
+## Example exports
+
+- `Default`
+- `EmptyDropzoneOnly`
+- `MixedItemStates`
+- `LiveSimulatedUpload`
+- `LocalisedFrench`
+

package/.agents/skills/component-library-rules/references/components/common__brand.md

@@ -0,0 +1,81 @@
+---
+id: common/brand
+title: "Common · Brand"
+description: "Logo + AppLogo (sized variants). Source images expected at /assets/media/gct-logo[-light].png."
+layer: common
+family: "Branding"
+sourcePath: src/preview/_brand
+examples:
+  - LogoExample
+  - AppLogoSizes
+  - AppLogoVariants
+imports:
+  - @/preview/_brand/app-logo
+  - @/preview/_brand/logo
+tags:
+  - common
+  - branding
+  - _brand
+  - brand
+  - logo
+  - applogo
+  - sized
+---
+
+# Common · Brand
+
+Logo + AppLogo (sized variants). Source images expected at /assets/media/gct-logo[-light].png.
+
+**Layer:** `common`  
+**Source:** `src/preview/_brand`
+
+## Examples
+
+```tsx
+import Logo from '@/preview/_brand/logo';
+import AppLogo from '@/preview/_brand/app-logo';
+import { Row, Col } from '../../PreviewLayout';
+
+export function LogoExample() {
+	return (
+		<>
+			<Col>
+								<Logo className="w-40 h-auto" />
+								<Logo className="w-40 h-auto" inverted />
+							</Col>
+		</>
+	);
+}
+
+export function AppLogoSizes() {
+	return (
+		<>
+			<Row>
+								<AppLogo size="small" />
+								<AppLogo size="medium" />
+								<AppLogo size="large" />
+							</Row>
+		</>
+	);
+}
+
+export function AppLogoVariants() {
+	return (
+		<>
+			<Row>
+								<AppLogo variant="dark" />
+								<div className="rounded-md bg-foreground p-3">
+									<AppLogo variant="light" />
+								</div>
+							</Row>
+		</>
+	);
+}
+```
+
+## Example exports
+
+- `LogoExample`
+- `AppLogoSizes`
+- `AppLogoVariants`
+

package/.agents/skills/component-library-rules/references/components/composed__admin.md

@@ -0,0 +1,128 @@
+---
+id: composed/admin
+title: "Composed · Admin"
+description: "Team list, permissions, conversations, settings, inventory."
+layer: composed
+family: "Admin"
+sourcePath: src/components/composed/admin
+examples:
+  - TeamMembers
+  - RolePermissions
+  - RecentConversations
+  - SettingsToggles
+  - InventoryLevel
+imports:
+  - @/components/base/cards
+  - @/components/composed/admin/conversation-row
+  - @/components/composed/admin/inventory-level
+  - @/components/composed/admin/role-permission
+  - @/components/composed/admin/settings-toggle
+  - @/components/composed/admin/team-member
+tags:
+  - composed
+  - admin
+  - team
+  - list
+  - permissions
+  - conversations
+---
+
+# Composed · Admin
+
+Team list, permissions, conversations, settings, inventory.
+
+**Layer:** `composed`  
+**Source:** `src/components/composed/admin`
+
+## Examples
+
+```tsx
+import { MessageSquare, Shield, Settings, Zap } from 'lucide-react';
+import { TeamMemberRow } from '@/components/composed/admin/team-member';
+import { RolePermissionCard } from '@/components/composed/admin/role-permission';
+import { RecentConversationRow } from '@/components/composed/admin/conversation-row';
+import { SettingsToggleRow } from '@/components/composed/admin/settings-toggle';
+import { InventoryLevelCard } from '@/components/composed/admin/inventory-level';
+import { SmartCard } from '@/components/base/cards';
+
+export function TeamMembers() {
+	return (
+		<>
+			<SmartCard>
+								<TeamMemberRow
+									members={[
+										{ initials: 'EM', name: 'Emma Garcia', role: 'Product Manager', dept: 'Operations', active: '2h ago' },
+										{ initials: 'SP', name: 'Daniel Smith', role: 'Lead Developer', dept: 'Engineering', active: '15m ago' },
+										{ initials: 'ID', name: 'David Williams', role: 'Designer', dept: 'Design', active: '1d ago' },
+									]}
+								/>
+							</SmartCard>
+		</>
+	);
+}
+
+export function RolePermissions() {
+	return (
+		<>
+			<RolePermissionCard
+								roleName="Editor"
+								description="Can manage content and view users."
+								memberCount={12}
+								sections={[
+									{ name: 'Content', permissions: [{ label: 'Create', active: true }, { label: 'Read', active: true }, { label: 'Update', active: true }, { label: 'Delete', active: false }] },
+									{ name: 'Users', permissions: [{ label: 'Invite', active: true }, { label: 'View', active: true }, { label: 'Edit', active: false }, { label: 'Remove', active: false }] },
+								]}
+								onEdit={() => {}}
+							/>
+		</>
+	);
+}
+
+export function RecentConversations() {
+	return (
+		<>
+			<SmartCard>
+								<RecentConversationRow
+									conversations={[
+										{ initials: 'EM', name: 'Emma Garcia', preview: 'Thanks for the quick response! I wanted to ask about the delivery timeline...', time: '2m', unread: 3 },
+										{ initials: 'SP', name: 'Daniel Smith', preview: 'The new product photos look great. Can we schedule a meeting...', time: '15m', unread: 0 },
+										{ initials: 'NK', name: 'Nadia Kowalski', preview: 'I noticed the voucher codes are not applying correctly...', time: '1h', unread: 1 },
+									]}
+								/>
+							</SmartCard>
+		</>
+	);
+}
+
+export function SettingsToggles() {
+	return (
+		<>
+			<SettingsToggleRow
+								settings={[
+									{ key: 'notifications', icon: MessageSquare, name: 'Push Notifications', desc: 'Receive alerts for new orders and messages', defaultValue: true },
+									{ key: 'twoFactor', icon: Shield, name: 'Two-Factor Auth', desc: 'Add an extra layer of security' },
+									{ key: 'darkMode', icon: Settings, name: 'Dark Mode', desc: 'Use dark theme across all admin pages', defaultValue: true },
+									{ key: 'analytics', icon: Zap, name: 'Usage Analytics', desc: 'Help us improve by sharing anonymous usage data', defaultValue: true },
+								]}
+							/>
+		</>
+	);
+}
+
+export function InventoryLevel() {
+	return (
+		<>
+			<InventoryLevelCard productName="Luxury Gift Basket" variant="Large / Gold" stock={23} reorderLevel={20} maxStock={100} lastRestocked="Mar 15" />
+		</>
+	);
+}
+```
+
+## Example exports
+
+- `TeamMembers`
+- `RolePermissions`
+- `RecentConversations`
+- `SettingsToggles`
+- `InventoryLevel`
+