@jamesodwyer/gds-figma-vite 2.0.12 → 2.0.14

package/guidelines/Guidelines.md

@@ -194,6 +194,115 @@ import { Modal, Card, InputField, Accordion, TextStyle } from '@jamesodwyer/gds-
 
 ---
 
+## 🚫 VALIDATION MESSAGES - ONLY SHOW ON ERROR
+
+**`InputField.Validation` is for ERROR messages only. Do NOT show it by default.**
+
+```tsx
+// ❌ WRONG - Validation always visible (even without error)
+<InputField id="email">
+  <InputField.Label>Email</InputField.Label>
+  <InputField.Row style={{ marginTop: '8px' }}>
+    <InputField.Input type="email" />
+  </InputField.Row>
+  <InputField.Validation type="error" screenReaderErrorPrefix="Error:">
+    We'll never share your email
+  </InputField.Validation>
+</InputField>
+
+// ✅ CORRECT - Only show validation when there IS an error
+<InputField id="email">
+  <InputField.Label>Email</InputField.Label>
+  <InputField.Row style={{ marginTop: '8px' }}>
+    <InputField.Input type="email" isErrored={hasError} />
+  </InputField.Row>
+  {hasError && (
+    <InputField.Validation type="error" screenReaderErrorPrefix="Error:">
+      Please enter a valid email address
+    </InputField.Validation>
+  )}
+</InputField>
+```
+
+### Helper Text vs Error Messages
+
+- **Helper text** (like "We'll never share your email") = Use a regular `<p>` or `TextStyle.Snowdon`
+- **Error messages** (like "Please enter a valid email") = Use `InputField.Validation` with conditional rendering
+
+```tsx
+// ✅ CORRECT - Helper text with regular element, error only when needed
+<InputField id="email">
+  <InputField.Label>Email</InputField.Label>
+  <InputField.Row style={{ marginTop: "8px" }}>
+    <InputField.Input type="email" isErrored={hasError} />
+  </InputField.Row>
+  {hasError ? (
+    <InputField.Validation type="error" screenReaderErrorPrefix="Error:">
+      Please enter a valid email address
+    </InputField.Validation>
+  ) : (
+    <p style={{ fontSize: "12px", color: "#666", marginTop: "4px" }}>
+      We'll never share your email with anyone else.
+    </p>
+  )}
+</InputField>
+```
+
+---
+
+## 🎨 TEXT & BACKGROUND COLORS - CONTRAST RULES
+
+**Always ensure text is readable against backgrounds:**
+
+| Background                            | Text Color                                  |
+| ------------------------------------- | ------------------------------------------- |
+| Light (white, `theme.base.bg`)        | Dark text (`theme.text.primary` = #121212)  |
+| Dark (`theme.base.bgInverse`, cosmos) | Light text (`theme.text.inverse` = #ffffff) |
+
+### Using Theme Colors for Contrast
+
+```tsx
+import styled from "styled-components";
+
+// ✅ CORRECT - Light background with dark text
+const LightSection = styled.div`
+  background: ${(props) => props.theme.base.bg};
+  color: ${(props) => props.theme.text.primary};
+`;
+
+// ✅ CORRECT - Dark background with light text
+const DarkSection = styled.div`
+  background: ${(props) => props.theme.base.bgInverse};
+  color: ${(props) => props.theme.text.inverse};
+`;
+
+// ✅ CORRECT - Brand colored background with white text
+const BrandSection = styled.div`
+  background: ${(props) => props.theme.base.primary};
+  color: #ffffff;
+`;
+```
+
+### Default Text Colors
+
+- **Light backgrounds**: Text is automatically dark (#121212)
+- **GDS components**: Already have correct text colors built-in
+- **Custom sections**: You must set the text color if you change the background
+
+```tsx
+// ❌ WRONG - Dark background but no text color set (text will be dark/invisible)
+<div style={{ background: '#121212' }}>
+  <TitleHeading>Can't read this!</TitleHeading>
+</div>
+
+// ✅ CORRECT - Dark background with white text
+<div style={{ background: '#121212', color: '#ffffff' }}>
+  <TitleHeading>Now visible!</TitleHeading>
+</div>
+```
+
+---
+
 ## Package Information
 
 - **Package Name**: `@jamesodwyer/gds-figma-vite`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jamesodwyer/gds-figma-vite",
-  "version": "2.0.12",
+  "version": "2.0.14",
   "publishConfig": {
     "access": "public"
   },