Establish cursor rules

2026-04-18 09:33:24 -06:00
parent 4854c49c4a
commit f866d11ff8
30 changed files with 1711 additions and 144 deletions
@@ -0,0 +1,59 @@
+---
+description: Figma ↔ codebase prop alignment & normalization for design-system components
+globs: app/components/**/*.{ts,tsx}
+alwaysApply: false
+---
+
+# Component prop alignment
+
+Figma emits PascalCase enum values (`"Standard"`, `"Inverse"`); the codebase
+stores lowercase (`"standard"`, `"inverse"`). Components must accept **both**,
+normalize to lowercase internally, and never break existing consumer call
+sites.
+
+## Scope
+
+Applies to enum-like string props: `variant`, `size`, `state`, `mode`, `type`,
+`position`, `alignment`, `status`, `color`, `palette`. **Skip** for free-form
+strings (URLs, classNames), booleans, numbers, or internal-only props.
+
+## Pattern
+
+```typescript
+// Type accepts both formats
+export type ComponentSizeValue = "small" | "medium" | "Small" | "Medium";
+
+// Container normalizes via helpers from lib/propNormalization.ts
+import { normalizeSize } from "../../../lib/propNormalization";
+
+const ComponentContainer = ({ size: sizeProp = "small" }: Props) => {
+  const size = normalizeSize(sizeProp, SIZE_OPTIONS, "small");
+  return <ComponentView size={size} />;
+};
+```
+
+## Normalizers
+
+Use an existing helper from `lib/propNormalization.ts` before writing a new
+one. Generic: `normalizeMode`, `normalizeState`, `normalizeInputState`,
+`normalizeSize`, `normalizeAlignment`, `normalizeSmallMediumLargeSize`,
+`normalizeLabelVariant`. Component-specific variants are named
+`normalize<Component><Prop>` (e.g. `normalizeChipPalette`,
+`normalizeButtonState`) — add one there rather than inlining a switch in your
+container.
+
+## Figma traceability
+
+Every DS component's container docstring cites its Figma origin so designers
+and engineers can jump between the two. Format: `Figma: "<Component Path>"
+(<node-id>)`.
+
+```typescript
+/**
+ * Figma: "Control / Incrementer" (`17857:30943`). A compact [ - value + ]
+ * row used for numeric step inputs…
+ */
+```
+
+When the view renders a distinct Figma node, add `data-figma-node="<id>"` on
+the root element for quick DOM-to-design lookup.