@publicplan/kern-react-kit 1.3.1 → 1.3.3

package/dist/skills/kern-react-kit/SKILL.md

@@ -0,0 +1,343 @@
+---
+name: kern-react-kit
+description: |
+  A production-ready React component library providing accessible, composable UI components 
+  for building consistent user interfaces. Use this skill when integrating @publicplan/kern-react-kit 
+  into React/TypeScript projects, building component-based UIs with accessibility-first design, 
+  or implementing design systems with EUPL-licensed components.
+license: EUPL-1.2
+compatibility: |
+  Designed for coding agents operating on JavaScript/TypeScript repositories. 
+  Compatible with React 18.2+ and React 19.1+. No network requirements for skill loading.
+metadata:
+  author: publicplan
+  package: "@publicplan/kern-react-kit"
+  repository: https://github.com/publicplan-internal/kern-components-public-part
+---
+
+# Kern React Kit Skill
+
+A composable, accessible React component library for professional UI development.
+
+## When to Use This Skill
+
+Use **kern-react-kit** when:
+- Building React applications that need production-grade UI components
+- Implementing design systems with accessibility (WCAG 2.1 AA) standards
+- Creating forms, layouts, dialogs, tables, and complex interactive components
+- Ensuring design consistency across multiple projects within an organization
+- Working in TypeScript codebases that benefit from full type safety
+
+## Key Principles
+
+1. **Composability**: Components use composition patterns; avoid monolithic imports
+2. **Accessibility**: All interactive components must follow WCAG 2.1 AA standards
+3. **Type Safety**: Components export TypeScript interfaces for all props
+4. **Theming**: CSS variables control styling; override via `--kern-*` custom properties
+5. **No External Globals**: Each component is self-contained; no implicit side effects
+
+## Public Import Rules
+
+### ✅ Correct Imports
+```typescript
+// Main entry point (recommended)
+import { Button, Card, Alert } from '@publicplan/kern-react-kit';
+
+// Component-specific imports (also valid)
+import { Button } from '@publicplan/kern-react-kit/Button';
+
+// Type-only imports
+import type { ButtonProps, CardProps } from '@publicplan/kern-react-kit';
+```
+
+### ❌ Forbidden Imports
+- **Do NOT** import from `dist/` directly in source code
+- **Do NOT** import internal/private components (those not exported in `src/index.ts`)
+- **Do NOT** import deep from component internals (e.g., `@publicplan/kern-react-kit/Button/internal`)
+- **Do NOT** import styles outside the main entry point
+
+### Library Exports
+The public API includes (non-exhaustive):
+- `Accordion`, `Alert`, `Badge`, `Body`, `Button`, `Card`, `Divider`, `Fieldset`
+- `Grid`, `Heading`, `Icon`, `Label`, `Link`, `Lists`, `Loader`, `Progress`
+- `Summary`, `Table`, `TaskList`, `ThemeProvider`, `Title`, `Dialog`, and more
+- Input components: `TextInput`, `TextareaInput`, `CheckboxInput`, `RadioInput`, `SelectInput`,
+  `EmailInput`, `UrlInput`, `TelInput`, `DateInput`, `PasswordInput`, `NumberInput`, `FileInput`,
+  `CheckboxList`
+
+See **references/COMPONENTS.md** for a more complete list and usage patterns.
+
+## Styling & Theming
+
+### CSS Custom Properties
+All components respect `--kern-*` CSS variables. Key examples:
+- `--kern-color-primary`, `--kern-color-secondary`
+- `--kern-spacing-*` (unit-based spacing scale)
+- `--kern-radius-*` (border radius scale)
+- `--kern-shadow-*` (elevation shadows)
+- `--kern-font-*` (typography scale)
+
+### Overriding Styles
+```tsx
+import { Button } from '@publicplan/kern-react-kit';
+import './my-button-styles.css'; // Your custom styles
+
+// my-button-styles.css
+:root {
+  --kern-color-primary: #your-color;
+  --kern-spacing-lg: 2rem;
+}
+```
+
+### Global Styles
+Import the base stylesheet in your app entry point:
+```typescript
+import '@publicplan/kern-react-kit/index.css';
+```
+
+### SCSS Variables
+Component styling uses SCSS internally. Avoid relying on internal SCSS exports; use CSS variables instead.
+
+## Composition Patterns
+
+### Namespace Composition
+Some components use namespace composition. Assign a component to a namespace export:
+```typescript
+import { Card, Button } from '@publicplan/kern-react-kit';
+
+// Card is composed with sub-components like Media, Container, Header, Body, Footer
+function MyLayout() {
+  return (
+    <Card style={{ maxWidth: '320px' }}>
+      <Card.Media src="https://placehold.co/600x400?text=MEDIA" alt="Card media" />
+      <Card.Container>
+        <Card.Header>
+          <Card.Preline>Preline</Card.Preline>
+          <Card.Title>Title</Card.Title>
+          <Card.Subline>Subline</Card.Subline>
+        </Card.Header>
+        <Card.Body>Content goes here</Card.Body>
+        <Card.Footer>
+          <Button variant="primary" text="Primäraktion" />
+          <Button variant="secondary" text="Aktion" />
+        </Card.Footer>
+      </Card.Container>
+    </Card>
+  );
+}
+```
+
+### Compound Components
+Components like `Dialog`, `Accordion`, and `Table` use compound component patterns:
+```typescript
+import { Dialog, Accordion } from '@publicplan/kern-react-kit';
+
+// Dialog compound pattern
+<Dialog disableOverlayClose={false}>
+  <Dialog.Trigger>
+    <Button variant="primary" text="Open Dialog" />
+  </Dialog.Trigger>
+  <Dialog.Modal>
+    <Dialog.Header dialogTitle="Frage?" hasCloseButton />
+    <Dialog.Content>Are you sure?</Dialog.Content>
+    <Dialog.Footer>
+      <Dialog.Button variant="secondary" title="Abbrechen" />
+      <Dialog.Button variant="primary" title="Löschen" />
+    </Dialog.Footer>
+  </Dialog.Modal>
+</Dialog>
+
+// Accordion compound pattern
+<Accordion.Root>
+  <Accordion.Summary title={{ title: 'Accordion 1', textWrapper: 'h2' }} />
+  <Accordion.Content>Details here</Accordion.Content>
+</Accordion.Root>
+```
+
+## Accessibility Requirements
+
+### Mandatory Practices
+1. **Interactive Components**: All buttons, links, inputs must have accessible names (`aria-label`, `aria-labelledby`, or text content)
+2. **Forms**: Prefer labeled inputs using `TextInput`'s `label` prop or `Label` with explicit `htmlFor`
+3. **Color Contrast**: Do not rely on color alone; use icons, text, or patterns for information
+4. **Keyboard Navigation**: All interactive components support Tab, Enter, Escape, and arrow keys
+5. **ARIA**: Use `aria-*` attributes for dynamic state (expanded, disabled, hidden, etc.)
+6. **Icons in Alerts/Links**: Icons are `aria-hidden="true"` by default. If the icon conveys meaning, set `aria-hidden={false}` and provide `aria-label`.
+
+### Testing Accessibility
+```typescript
+// Example vitest + vitest-axe test pattern
+import { render } from '@testing-library/react';
+import { axe, toHaveNoViolations } from 'vitest-axe';
+import { Button } from '@publicplan/kern-react-kit';
+
+expect.extend(toHaveNoViolations);
+
+test('Button has no accessibility violations', async () => {
+  const { container } = render(<Button>Click me</Button>);
+  const results = await axe(container);
+  expect(results).toHaveNoViolations();
+});
+```
+
+## Common Recipes
+
+### Recipe 1: Form with Validation
+```typescript
+import { Fieldset, TextInput, CheckboxInput, Button } from '@publicplan/kern-react-kit';
+import { useState } from 'react';
+
+export function MyForm() {
+  const [errors, setErrors] = useState<Record<string, string>>({});
+
+  const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    const formData = new FormData(e.currentTarget);
+    const name = formData.get('name') as string;
+    
+    if (!name) {
+      setErrors({ name: 'Der Name darf nicht leer sein' });
+      return;
+    }
+    // Submit logic
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <Fieldset.Root>
+        <Fieldset.Legend>Ansprechpartner</Fieldset.Legend>
+        <Fieldset.Content>
+          <TextInput
+            id="name"
+            name="name"
+            label="Name"
+            error={errors.name}
+            aria-describedby={errors.name ? 'name-error' : undefined}
+            required
+          />
+          <CheckboxInput
+            id="privacy"
+            name="privacy"
+            label="Ich akzeptiere die Datenschutzerklärung"
+            required
+          />
+        </Fieldset.Content>
+        {errors.name && <Fieldset.Error id="name-error">{errors.name}</Fieldset.Error>}
+      </Fieldset.Root>
+      <Button type="submit" variant="primary" text="Submit" />
+    </form>
+  );
+}
+```
+
+### Recipe 2: Card Layout with Grid
+```typescript
+import { Card, Grid, Button } from '@publicplan/kern-react-kit';
+
+export function Dashboard() {
+  return (
+    <Grid>
+      <Grid.Row>
+        <Grid.Column width={4}>
+          <Card>
+            <Card.Container>
+              <Card.Header>
+                <Card.Title>Total Users</Card.Title>
+              </Card.Header>
+              <Card.Body>1,234</Card.Body>
+              <Card.Footer>
+                <Button variant="secondary" text="Details" />
+              </Card.Footer>
+            </Card.Container>
+          </Card>
+        </Grid.Column>
+        <Grid.Column width={4}>
+          <Card>
+            <Card.Container>
+              <Card.Header>
+                <Card.Title>Active Sessions</Card.Title>
+              </Card.Header>
+              <Card.Body>567</Card.Body>
+              <Card.Footer>
+                <Button variant="secondary" text="Details" />
+              </Card.Footer>
+            </Card.Container>
+          </Card>
+        </Grid.Column>
+        <Grid.Column width={4}>
+          <Card>
+            <Card.Container>
+              <Card.Header>
+                <Card.Title>Revenue</Card.Title>
+              </Card.Header>
+              <Card.Body>€45,678</Card.Body>
+              <Card.Footer>
+                <Button variant="secondary" text="Details" />
+              </Card.Footer>
+            </Card.Container>
+          </Card>
+        </Grid.Column>
+      </Grid.Row>
+    </Grid>
+  );
+}
+```
+
+### Recipe 3: Modal Dialog with Confirmation
+```typescript
+import { Dialog, Button } from '@publicplan/kern-react-kit';
+
+export function ConfirmDialog({ onConfirm }: { onConfirm: () => void }) {
+  return (
+    <Dialog disableOverlayClose={false}>
+      <Dialog.Trigger>
+        <Button variant="primary" text="Delete Item" />
+      </Dialog.Trigger>
+      <Dialog.Modal>
+        <Dialog.Header dialogTitle="Confirm Deletion" hasCloseButton />
+        <Dialog.Content>
+          This action cannot be undone. Are you sure?
+        </Dialog.Content>
+        <Dialog.Footer>
+          <Dialog.Button variant="secondary" title="Cancel" />
+          <Dialog.Button
+            variant="primary"
+            title="Delete"
+            onClick={(e, context) => {
+              onConfirm();
+              context.closeDialog();
+            }}
+          />
+        </Dialog.Footer>
+      </Dialog.Modal>
+    </Dialog>
+  );
+}
+```
+
+## Testing & Storybook
+
+### Unit Tests
+- Components are tested with **vitest** and **@testing-library/react**
+- All tests live in `__tests__/components/`
+- Run tests: `npm test` or `npm run test:watch` for development
+
+### Storybook Stories
+- Interactive documentation: `npm run storybook`
+- All components have Storybook stories for isolated development and testing
+- Stories are co-located with components (e.g., `Button.stories.tsx`)
+
+### E2E Tests
+- Playwright tests in `__tests__/e2e/`
+- Run: `npm run test:e2e`
+
+## Further Reference
+
+For deeper technical details, see:
+- **references/REFERENCE.md**: Installation, API stability, theming rules, and testing expectations
+- **references/COMPONENTS.md**: Component catalog with import paths, prop interfaces, and usage examples
+
+---
+
+*Last updated: 2026-03-03*
+*Package: @publicplan/kern-react-kit@1.0.1*