@urbint/cl 1.0.1

package/.cursor/rules

@@ -0,0 +1,313 @@
+# Cursor Rules – Cross-Platform React Native Component Library
+## Using Unistyles + Storybook (Web, iOS, Android)
+
+---
+
+## 1. Project Scope & Intent
+
+This repository is a **shared UI component library** used across:
+
+- React Native (iOS)
+- React Native (Android)
+- React Native Web
+
+The library must be:
+
+- Theme-driven
+- Platform-agnostic
+- Accessible
+- Performant
+- Strictly typed
+- Reusable across multiple apps
+
+Cursor must **not** introduce app-specific logic.
+
+---
+
+## 2. Tech Stack (Non-Negotiable)
+
+Cursor must assume and follow:
+
+- React Native
+- TypeScript (strict mode)
+- react-native-unistyles
+- react-native-web compatibility
+- Storybook (React Native + Web)
+
+Explicitly forbidden:
+
+- Inline styles
+- StyleSheet.create
+- Tailwind / CSS-in-JS alternatives
+- Zustand / Redux
+- Side effects (analytics, storage, API calls)
+
+---
+
+## 3. Folder & Naming Conventions
+
+### Component Structure
+components/
+- Button/
+    Button.tsx
+    Button.styles.ts
+    Button.types.ts
+    Button.stories.tsx
+    index.ts
+
+
+### Rules
+
+- One component per folder
+- Logic, styles, and types must be separated
+- Barrel export (`index.ts`) is mandatory
+- Filenames must match component name
+- Component names must be PascalCase
+
+---
+
+## 4. Component Authoring Rules
+
+### Design Principles
+
+Components must be:
+
+- Pure
+- Stateless unless unavoidable
+- Controlled via props
+- Deterministic and predictable
+
+Forbidden:
+
+- Business logic
+- Navigation
+- Analytics
+- API calls
+- App-specific assumptions
+
+---
+
+## 5. Styling Rules (Unistyles)
+
+### Mandatory Pattern
+
+```ts
+import { createStyleSheet } from 'react-native-unistyles';
+
+export const stylesheet = createStyleSheet(theme => ({
+  container: {
+    paddingVertical: theme.spacing.sm,
+    paddingHorizontal: theme.spacing.md,
+    borderRadius: theme.radius.md,
+  },
+  text: {
+    color: theme.colors.text.primary,
+    fontSize: theme.typography.body.fontSize,
+  },
+}));
+
+Usage
+
+const { styles } = useStyles(stylesheet);
+
+Rules
+	•	❌ No inline styles
+	•	❌ No StyleSheet.create
+	•	❌ No hardcoded values
+	•	✅ Use semantic tokens from theme
+	•	✅ Support light & dark themes automatically
+
+
+6. Theme Contract Assumptions
+
+Cursor must assume these theme keys exist:
+
+theme.colors
+theme.spacing
+theme.radius
+theme.typography
+theme.shadows
+theme.zIndex
+
+Rules:
+	•	Do not invent new tokens casually
+	•	Prefer semantic tokens over raw intent
+	•	Components must work with any theme
+
+
+7. Props & Type Rules
+
+export interface ButtonProps {
+  label: string;
+  variant?: 'primary' | 'secondary' | 'ghost';
+  size?: 'sm' | 'md' | 'lg';
+  disabled?: boolean;
+  onPress?: () => void;
+}
+
+Rules:
+	•	No any
+	•	Explicit props only
+	•	Optional props must have defaults
+	•	Use discriminated unions when behavior differs
+	•	Avoid extending native props unless necessary
+
+
+8. Accessibility (Mandatory)
+
+Every interactive component must:
+	•	Support accessibilityLabel
+	•	Define accessibilityRole
+	•	Respect font scaling
+	•	Respect reduced motion preferences
+	•	Use Pressable instead of Touchable*
+
+Accessibility is not optional.
+
+
+9. Platform Compatibility Rules
+
+Components must:
+	•	Work on iOS, Android, and Web
+	•	Avoid DOM-only APIs
+	•	Avoid native-only APIs
+	•	Use Platform.select() only when unavoidable
+
+No pixel-perfect assumptions.
+
+
+10. Performance Rules
+	•	Avoid anonymous functions in render
+	•	Use memo where appropriate
+	•	No heavy calculations during render
+	•	No unnecessary re-renders
+
+11. Storybook (Mandatory)
+
+Storybook is the source of truth for:
+	•	Visual validation
+	•	Theme coverage
+	•	Accessibility review
+	•	Cross-platform parity
+
+Every component must include a story.
+
+13. Storybook Stack Assumptions
+
+Cursor must assume:
+	•	@storybook/react-native
+	•	@storybook/react (for web)
+	•	TypeScript stories
+	•	CSF (Component Story Format)
+
+
+14. Story Placement
+
+Stories must be co-located with components:
+components/Button/Button.stories.tsx
+No global stories folder.
+
+15. Story Format (Required)
+
+import type { Meta, StoryObj } from '@storybook/react';
+import { Button } from './Button';
+
+const meta: Meta<typeof Button> = {
+  title: 'Components/Button',
+  component: Button,
+  argTypes: {
+    onPress: { action: 'pressed' },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Button>;
+
+export const Primary: Story = {
+  args: {
+    label: 'Primary Button',
+    variant: 'primary',
+  },
+};
+
+Rules:
+	•	Use args, not inline JSX
+	•	No anonymous components
+	•	No logic inside stories
+
+
+
+16. Theme Integration in Storybook
+
+Storybook must use a theme decorator:
+
+<UnistylesThemeProvider theme="light">
+  <Story />
+</UnistylesThemeProvider>
+Rules:
+	•	All stories must render in light & dark themes
+	•	No hardcoded colors
+	•	Prefer toolbar theme switching
+
+
+17. Story Coverage Requirements
+
+Each component must include stories for:
+	•	Default state
+	•	All variants
+	•	Disabled state
+	•	Edge cases (long text, overflow)
+	•	Interaction states
+
+⸻
+
+18. Controls & Actions
+	•	All public props must be exposed via args
+	•	Use Storybook actions for callbacks
+	•	No console logging
+
+19. Accessibility in Storybook
+
+Stories must:
+	•	Include accessible labels
+	•	Be keyboard navigable on web
+	•	Avoid visual-only meaning
+
+Optional:
+	•	@storybook/addon-a11y
+
+⸻
+
+20. Cross-Platform Story Rules
+
+Stories must:
+	•	Render on iOS, Android, and Web
+	•	Avoid platform-specific hacks
+	•	Avoid DOM APIs
+
+21. Documentation Stories (Preferred)
+
+Core components should include documentation stories using Storybook Docs.
+
+⸻
+
+22. What Cursor Must NEVER Do
+
+❌ Add navigation
+❌ Add analytics
+❌ Add API calls
+❌ Add state management
+❌ Hardcode styles
+❌ Skip Storybook
+❌ Break web compatibility
+
+23. Quality Gate Before Completion
+
+Cursor must verify:
+	•	TypeScript passes
+	•	Component renders on web
+	•	Theme-driven styling
+	•	Accessibility compliance
+	•	Storybook coverage exists
+	•	Clean public exports

package/.rnstorybook/index.ts

@@ -0,0 +1,11 @@
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import { view } from './storybook.requires';
+
+const StorybookUIRoot = view.getStorybookUI({
+  storage: {
+    getItem: AsyncStorage.getItem,
+    setItem: AsyncStorage.setItem,
+  },
+});
+
+export default StorybookUIRoot;

package/.rnstorybook/main.ts

@@ -0,0 +1,8 @@
+import type { StorybookConfig } from '@storybook/react-native';
+
+const main: StorybookConfig = {
+  stories: ['./stories/**/*.stories.?(ts|tsx|js|jsx)'],
+  addons: ['@storybook/addon-ondevice-controls', '@storybook/addon-ondevice-actions'],
+};
+
+export default main;

package/.rnstorybook/preview.tsx

@@ -0,0 +1,14 @@
+import type { Preview } from '@storybook/react-native';
+
+const preview: Preview = {
+  parameters: {
+    controls: {
+      matchers: {
+        color: /(background|color)$/i,
+        date: /Date$/,
+      },
+    },
+  },
+};
+
+export default preview;

package/.rnstorybook/storybook.requires.ts

@@ -0,0 +1,49 @@
+/* do not change this file, it is auto generated by storybook. */
+
+import { start, updateView } from '@storybook/react-native';
+
+import '@storybook/addon-ondevice-controls/register';
+import '@storybook/addon-ondevice-actions/register';
+
+const normalizedStories = [
+  {
+    titlePrefix: '',
+    directory: './.rnstorybook/stories',
+    files: '**/*.stories.?(ts|tsx|js|jsx)',
+    importPathMatcher:
+      /^\.(?:(?:^|\/|(?:(?:(?!(?:^|\/)\.).)*?)\/)(?!\.)(?=.)[^/]*?\.stories\.(?:ts|tsx|js|jsx)?)$/,
+    // @ts-ignore
+    req: require.context(
+      './stories',
+      true,
+      /^\.(?:(?:^|\/|(?:(?:(?!(?:^|\/)\.).)*?)\/)(?!\.)(?=.)[^/]*?\.stories\.(?:ts|tsx|js|jsx)?)$/
+    ),
+  },
+];
+
+declare global {
+  var view: ReturnType<typeof start>;
+  var STORIES: typeof normalizedStories;
+}
+
+const annotations = [
+  require('./preview'),
+  require('@storybook/react-native/dist/preview'),
+  require('@storybook/addon-ondevice-actions/preview'),
+];
+
+global.STORIES = normalizedStories;
+
+// @ts-ignore
+module?.hot?.accept?.();
+
+if (!global.view) {
+  global.view = start({
+    annotations,
+    storyEntries: normalizedStories,
+  });
+} else {
+  updateView(global.view, annotations, normalizedStories);
+}
+
+export const view = global.view;

package/.storybook/main.ts

@@ -0,0 +1,16 @@
+import type { StorybookConfig } from '@storybook/react-native-web-vite';
+
+const config: StorybookConfig = {
+  "stories": [
+    "../src/**/*.mdx",
+    "../src/**/*.stories.@(js|jsx|mjs|ts|tsx)"
+  ],
+  "addons": [
+    "@chromatic-com/storybook",
+    "@storybook/addon-vitest",
+    "@storybook/addon-a11y",
+    "@storybook/addon-docs"
+  ],
+  "framework": "@storybook/react-native-web-vite"
+};
+export default config;

package/.storybook/preview.ts

@@ -0,0 +1,32 @@
+import type { Preview } from '@storybook/react-native-web-vite';
+
+// Import Unistyles configuration - this is required for styled components
+import '../src/styles/unistyles';
+
+const preview: Preview = {
+  parameters: {
+    controls: {
+      matchers: {
+        color: /(background|color)$/i,
+        date: /Date$/i,
+      },
+    },
+    a11y: {
+      // 'todo' - show a11y violations in the test UI only
+      // 'error' - fail CI on a11y violations
+      // 'off' - skip a11y checks entirely
+      test: 'todo',
+    },
+    layout: 'centered',
+    backgrounds: {
+      default: 'light',
+      values: [
+        { name: 'light', value: '#ffffff' },
+        { name: 'dark', value: '#1a1a2e' },
+        { name: 'gray', value: '#f5f5f5' },
+      ],
+    },
+  },
+};
+
+export default preview;

package/.storybook/vitest.setup.ts

@@ -0,0 +1,7 @@
+import * as a11yAddonAnnotations from "@storybook/addon-a11y/preview";
+import { setProjectAnnotations } from '@storybook/react-native-web-vite';
+import * as projectAnnotations from './preview';
+
+// This is an important step to apply the right configuration when testing your stories.
+// More info at: https://storybook.js.org/docs/api/portable-stories/portable-stories-vitest#setprojectannotations
+setProjectAnnotations([a11yAddonAnnotations, projectAnnotations]);