@fpkit/acss 0.6.2 → 1.0.0-beta.1

package/src/components/form/form.stories.tsx

@@ -628,3 +628,274 @@ export const WithOnEnterHandler: Story = {
     });
   },
 };
+
+/**
+ * CSS Variable Customization
+ *
+ * Demonstrates how to customize form/input appearance using the new standardized
+ * CSS custom property naming convention.
+ *
+ * New variable naming patterns:
+ * - Logical properties: `--input-padding-inline`, `--input-padding-block`
+ * - Full property names: `--input-width`, `--input-radius`, `--input-border`
+ * - Approved abbreviations: `--input-fs` (font-size), `--input-bg` (background)
+ * - State variables: `--input-focus-outline`, `--input-disabled-bg`
+ */
+export const Customization: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '2rem' }}>
+      {/* Custom input styling */}
+      <div>
+        <h4>Custom Input Styling</h4>
+        <FormComponent aria-label="Custom input example">
+          <FormComponent.Field label="Name" labelFor="custom-name">
+            <FormComponent.Input
+              id="custom-name"
+              name="name"
+              placeholder="Enter your name"
+              styles={{
+                "--input-padding-inline": "1.5rem",
+                "--input-padding-block": "0.75rem",
+                "--input-fs": "1.125rem",
+                "--input-radius": "0.5rem",
+                "--input-border": "2px solid #0066cc",
+              }}
+            />
+          </FormComponent.Field>
+        </FormComponent>
+      </div>
+
+      {/* Compact form */}
+      <div>
+        <h4>Compact Form</h4>
+        <FormComponent aria-label="Compact form example">
+          <FormComponent.Field label="Email" labelFor="compact-email">
+            <FormComponent.Input
+              id="compact-email"
+              name="email"
+              type="email"
+              styles={{
+                "--input-padding-inline": "0.75rem",
+                "--input-padding-block": "0.5rem",
+                "--input-fs": "0.875rem",
+                "--input-radius": "0.25rem",
+              }}
+            />
+          </FormComponent.Field>
+        </FormComponent>
+      </div>
+
+      {/* Custom focus states */}
+      <div>
+        <h4>Custom Focus States</h4>
+        <FormComponent aria-label="Focus state example">
+          <FormComponent.Field label="Username" labelFor="focus-username">
+            <FormComponent.Input
+              id="focus-username"
+              name="username"
+              placeholder="Try focusing this input"
+              styles={{
+                "--input-focus-outline": "3px solid #0066cc",
+                "--input-focus-outline-offset": "2px",
+                "--input-border": "2px solid #ddd",
+              }}
+            />
+          </FormComponent.Field>
+        </FormComponent>
+      </div>
+
+      {/* Custom textarea */}
+      <div>
+        <h4>Custom Textarea</h4>
+        <FormComponent aria-label="Textarea example">
+          <FormComponent.Field label="Message" labelFor="custom-message">
+            <FormComponent.Textarea
+              id="custom-message"
+              name="message"
+              placeholder="Enter your message"
+              rows={4}
+              styles={{
+                "--input-padding-inline": "1rem",
+                "--input-padding-block": "1rem",
+                "--input-fs": "1rem",
+                "--input-radius": "0.75rem",
+                "--input-border": "1px solid #ccc",
+                "--input-width": "100%",
+              }}
+            />
+          </FormComponent.Field>
+        </FormComponent>
+      </div>
+
+      {/* Custom select */}
+      <div>
+        <h4>Custom Select</h4>
+        <FormComponent aria-label="Select example">
+          <FormComponent.Field label="Country" labelFor="custom-country">
+            <FormComponent.Select
+              id="custom-country"
+              name="country"
+              styles={{
+                "--input-padding-inline": "1.25rem",
+                "--input-padding-block": "0.625rem",
+                "--input-fs": "1rem",
+                "--input-radius": "0.5rem",
+                "--input-border": "2px solid #28a745",
+                "--input-bg": "#f0f9f4",
+              }}
+            >
+              <FormComponent.Select.Option value="">Select country</FormComponent.Select.Option>
+              <FormComponent.Select.Option value="us">United States</FormComponent.Select.Option>
+              <FormComponent.Select.Option value="ca">Canada</FormComponent.Select.Option>
+              <FormComponent.Select.Option value="uk">United Kingdom</FormComponent.Select.Option>
+            </FormComponent.Select>
+          </FormComponent.Field>
+        </FormComponent>
+      </div>
+
+      {/* Dark theme example */}
+      <div
+        style={{
+          background: "#1a1a1a",
+          padding: "1.5rem",
+          borderRadius: "0.5rem",
+        }}
+      >
+        <h4 style={{ color: "white", marginTop: 0 }}>Dark Theme Example</h4>
+        <FormComponent aria-label="Dark theme form">
+          <FormComponent.Field label="Email" labelFor="dark-email">
+            <FormComponent.Input
+              id="dark-email"
+              name="email"
+              type="email"
+              placeholder="email@example.com"
+              styles={{
+                "--input-bg": "#2a2a2a",
+                "--input-color": "#e5e7eb",
+                "--input-border": "1px solid #4b5563",
+                "--input-padding-inline": "1rem",
+                "--input-padding-block": "0.75rem",
+                "--input-radius": "0.5rem",
+                "--input-focus-outline": "2px solid #3b82f6",
+                "--placeholder-color": "#9ca3af",
+              }}
+            />
+          </FormComponent.Field>
+          <FormComponent.Field label="Comments" labelFor="dark-comments" style={{ marginTop: "1rem" }}>
+            <FormComponent.Textarea
+              id="dark-comments"
+              name="comments"
+              placeholder="Your feedback..."
+              rows={3}
+              styles={{
+                "--input-bg": "#2a2a2a",
+                "--input-color": "#e5e7eb",
+                "--input-border": "1px solid #4b5563",
+                "--input-padding-inline": "1rem",
+                "--input-padding-block": "0.75rem",
+                "--input-radius": "0.5rem",
+                "--input-focus-outline": "2px solid #3b82f6",
+                "--placeholder-color": "#9ca3af",
+              }}
+            />
+          </FormComponent.Field>
+        </FormComponent>
+      </div>
+
+      {/* Disabled state customization */}
+      <div>
+        <h4>Custom Disabled State</h4>
+        <FormComponent aria-label="Disabled state example">
+          <FormComponent.Field label="Disabled Input" labelFor="disabled-custom">
+            <FormComponent.Input
+              id="disabled-custom"
+              name="disabled"
+              disabled
+              value="This input is disabled"
+              styles={{
+                "--input-disabled-bg": "#f5f5f5",
+                "--input-disabled-opacity": "0.6",
+                "--input-padding-inline": "1rem",
+                "--input-padding-block": "0.75rem",
+              }}
+            />
+          </FormComponent.Field>
+        </FormComponent>
+      </div>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: `
+## Available CSS Variables
+
+### Base Properties
+- \`--input-padding-inline\`: Horizontal padding (logical property)
+- \`--input-padding-block\`: Vertical padding (logical property)
+- \`--input-width\`: Input width
+- \`--input-radius\`: Border radius
+- \`--input-color\`: Text color
+- \`--input-bg\`: Background color
+- \`--input-border\`: Border style
+
+### Typography (Approved Abbreviations)
+- \`--input-fs\`: Font size
+
+### Focus State Variables
+- \`--input-focus-outline\`: Outline on focus
+- \`--input-focus-outline-offset\`: Outline offset on focus
+
+### Disabled State Variables
+- \`--input-disabled-bg\`: Background color when disabled
+- \`--input-disabled-opacity\`: Opacity when disabled
+
+### Placeholder Variables
+- \`--placeholder-fs\`: Placeholder font size
+- \`--placeholder-color\`: Placeholder text color
+
+### Migration from Old Names
+- ❌ \`--input-px\` → ✅ \`--input-padding-inline\`
+- ❌ \`--input-py\` → ✅ \`--input-padding-block\`
+- ❌ \`--input-w\` → ✅ \`--input-width\`
+
+## Usage Examples
+
+### Custom Input
+\`\`\`tsx
+<Form.Input
+  styles={{
+    "--input-padding-inline": "1.5rem",
+    "--input-padding-block": "0.75rem",
+    "--input-fs": "1.125rem",
+    "--input-radius": "0.5rem",
+  }}
+/>
+\`\`\`
+
+### Custom Focus State
+\`\`\`tsx
+<Form.Input
+  styles={{
+    "--input-focus-outline": "3px solid #0066cc",
+    "--input-focus-outline-offset": "2px",
+  }}
+/>
+\`\`\`
+
+### Dark Theme Input
+\`\`\`tsx
+<Form.Input
+  styles={{
+    "--input-bg": "#2a2a2a",
+    "--input-color": "#e5e7eb",
+    "--input-border": "1px solid #4b5563",
+    "--input-focus-outline": "2px solid #3b82f6",
+  }}
+/>
+\`\`\`
+        `,
+      },
+    },
+  },
+} as Story;

package/src/components/form/input.stories.tsx

@@ -221,3 +221,161 @@ export const UrlInput: Story = {
     expect(input).toHaveValue("https://example.com");
   },
 } as Story;
+
+/**
+ * CSS Variable Customization
+ *
+ * Demonstrates how to customize input appearance using the new standardized
+ * CSS custom property naming convention.
+ *
+ * New variable naming patterns:
+ * - Logical properties: `--input-padding-inline`, `--input-padding-block`
+ * - Full property names: `--input-width`, `--input-radius`, `--input-border`
+ * - Focus state variables: `--input-focus-outline`, `--input-focus-outline-offset`
+ * - Disabled state variables: `--input-disabled-bg`, `--input-disabled-opacity`
+ * - Approved abbreviations: `--input-fs` (font-size)
+ */
+export const Customization: Story = {
+  render: () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: "2rem", maxWidth: "600px" }}>
+      {/* Custom brand styling */}
+      <div>
+        <h4>Custom Brand Styling</h4>
+        <Input
+          type="text"
+          placeholder="Enter your email"
+          styles={{
+            "--input-padding-inline": "1rem",
+            "--input-padding-block": "0.75rem",
+            "--input-border": "2px solid #0066cc",
+            "--input-radius": "0.5rem",
+            "--input-fs": "1rem",
+          }}
+        />
+      </div>
+
+      {/* Custom focus indicator (WCAG compliant) */}
+      <div>
+        <h4>Custom Focus Indicator (WCAG AA Compliant)</h4>
+        <Input
+          type="text"
+          placeholder="Focus me to see custom outline"
+          styles={{
+            "--input-focus-outline": "3px solid #0066cc",
+            "--input-focus-outline-offset": "2px",
+            "--input-border": "1px solid #ccc",
+          }}
+        />
+      </div>
+
+      {/* Custom disabled state */}
+      <div>
+        <h4>Custom Disabled State</h4>
+        <Input
+          type="text"
+          disabled={true}
+          placeholder="Disabled input"
+          value="Cannot edit"
+          styles={{
+            "--input-disabled-bg": "#ffe6e6",
+            "--input-disabled-opacity": "0.7",
+            "--input-border": "1px dashed #999",
+          }}
+        />
+      </div>
+
+      {/* Compact input */}
+      <div>
+        <h4>Compact Input (Logical Properties)</h4>
+        <Input
+          type="text"
+          placeholder="Compact"
+          styles={{
+            "--input-padding-inline": "0.5rem",
+            "--input-padding-block": "0.25rem",
+            "--input-fs": "0.875rem",
+            "--input-width": "200px",
+          }}
+        />
+      </div>
+
+      {/* Spacious input */}
+      <div>
+        <h4>Spacious Input</h4>
+        <Input
+          type="text"
+          placeholder="Spacious"
+          styles={{
+            "--input-padding-inline": "1.5rem",
+            "--input-padding-block": "1rem",
+            "--input-fs": "1.125rem",
+            "--input-radius": "0.75rem",
+          }}
+        />
+      </div>
+
+      {/* Dark theme example */}
+      <div
+        style={{
+          background: "#1a1a1a",
+          padding: "1.5rem",
+          borderRadius: "0.5rem",
+        }}
+      >
+        <h4 style={{ color: "white", marginTop: 0 }}>Dark Theme Example</h4>
+        <Input
+          type="text"
+          placeholder="Search..."
+          styles={{
+            "--input-bg": "#2a2a2a",
+            "--input-color": "white",
+            "--input-border": "1px solid #4b5563",
+            "--input-focus-outline": "2px solid #3b82f6",
+            "--input-focus-outline-offset": "0",
+            "--placeholder-color": "#9ca3af",
+          }}
+        />
+      </div>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: `
+## Available CSS Variables
+
+### Base Properties
+- \`--input-padding-inline\`: Horizontal padding (logical property)
+- \`--input-padding-block\`: Vertical padding (logical property)
+- \`--input-width\`: Input width (default: clamp(200px, 100%, 500px))
+- \`--input-border\`: Border style
+- \`--input-radius\`: Border radius
+- \`--input-bg\`: Background color
+- \`--input-outline\`: Default outline
+
+### Typography (Approved Abbreviation)
+- \`--input-fs\`: Font size
+
+### Focus State Variables (NEW)
+- \`--input-focus-outline\`: Outline when focused
+- \`--input-focus-outline-offset\`: Outline offset (for WCAG compliance)
+
+### Disabled State Variables (NEW)
+- \`--input-disabled-bg\`: Background when disabled
+- \`--input-disabled-opacity\`: Opacity when disabled
+- \`--input-disabled-cursor\`: Cursor style when disabled
+
+### Placeholder Variables
+- \`--placeholder-color\`: Placeholder text color
+- \`--placeholder-fs\`: Placeholder font size
+- \`--placeholder-style\`: Placeholder font style (italic)
+
+### Migration from Old Names
+- ❌ \`--input-px\` → ✅ \`--input-padding-inline\`
+- ❌ \`--input-py\` → ✅ \`--input-padding-block\`
+- ❌ \`--input-w\` → ✅ \`--input-width\`
+        `,
+      },
+    },
+  },
+} as Story;

package/src/components/images/figure.stories.tsx

@@ -11,7 +11,47 @@ const meta: Meta<typeof Figure> = {
     actions: { argTypesRegex: "^on.*" },
     docs: {
       description: {
-        component: "Figure description here...",
+        component: `A semantic figure component for displaying images with captions, using CSS custom properties for flexible styling.
+
+## CSS Variables
+
+Customize the Figure and Image appearance using CSS custom properties:
+
+### Image Variables (img[alt])
+- \`--img-max-width\`: Maximum width (default: \`100%\`)
+- \`--img-height\`: Height value (default: \`auto\`)
+- \`--img-display\`: Display type (default: \`inline-block\`)
+- \`--img-object-fit\`: Object fit mode (default: \`cover\`)
+- \`--img-object-position\`: Object position (default: \`center\`)
+- \`--img-aspect-ratio\`: Aspect ratio (default: \`auto 2/3\`)
+
+### Figure Variables (figure:has(img[alt]))
+- \`--fig-display\`: Display type (default: \`flex\`)
+- \`--fig-padding\`: Figure padding (default: \`0.5rem\`)
+- \`--fig-bg\`: Background color (default: \`rgba(245, 245, 245, 0.683)\`)
+- \`--fig-width\`: Max width constraint (default: \`fit-content\`)
+- \`--fig-bottom\`: Figcaption bottom offset (default: \`var(--fig-padding)\`)
+- \`--fig-left\`: Figcaption left offset (default: \`var(--fig-padding)\`)
+- \`--fig-right\`: Figcaption right offset (default: \`var(--fig-padding)\`)
+
+### Figcaption Variables
+- \`--caption-padding\`: Caption padding (default: \`var(--spc-3)\`)
+
+**Example:**
+\`\`\`css
+figure:has(img[alt]) {
+  --fig-padding: 1rem;
+  --fig-bg: #f5f5f5;
+  --fig-width: 40rem;
+  --caption-padding: 1.5rem;
+}
+
+img[alt] {
+  --img-max-width: 100%;
+  --img-object-fit: contain;
+  --img-aspect-ratio: 16/9;
+}
+\`\`\``,
       },
     },
   },

package/src/components/images/img.scss

@@ -39,20 +39,20 @@ img[alt] {
 figure {
   &:has(img[alt]) {
     --fig-display: flex;
-    --fig-p: 0.5rem;
+    --fig-padding: 0.5rem;
     --fig-bg: rgba(245, 245, 245, 0.683);
-    --fig-w: fit-content;
+    --fig-width: fit-content;
     display: var(--fig-display);
     position: relative;
-    padding: var(--fig-p);
+    padding: var(--fig-padding);
     background-color: var(--fig-bg);
-    max-width: var(--fig-w);
+    max-width: var(--fig-width);
     > figcaption {
       position: absolute;
-      bottom: var(--fig-bottom, var(--fig-p));
-      left: var(--fig-left, var(--fig-p));
-      right: var(--fig-right, var(--fig-p));
-      padding: var(--caption-p, var(--spc-3));
+      bottom: var(--fig-bottom, var(--fig-padding));
+      left: var(--fig-left, var(--fig-padding));
+      right: var(--fig-right, var(--fig-padding));
+      padding: var(--caption-padding, var(--spc-3));
       background-color: var(--fig-bg);
     }
   }

package/src/components/images/img.scss.backup

@@ -0,0 +1,59 @@
+/**
+ * Image component styles
+ *
+ * Applies to all images with alt attribute (both decorative alt="" and semantic).
+ * Uses CSS custom properties for flexible theming and responsive behavior.
+ */
+img[alt] {
+  /* CSS Custom Properties - Override these for customization */
+  --img-max-width: 100%;
+  --img-height: auto;
+  --img-object-fit: cover;
+  --img-object-position: center;
+  --img-aspect-ratio: auto 2/3;
+  --img-display: inline-block;
+
+  /* Layout - Responsive by default */
+  max-width: var(--img-max-width);
+  max-inline-size: var(--img-max-width); /* Logical property for i18n */
+  block-size: var(--img-height);
+  display: var(--img-display);
+  vertical-align: middle;
+
+  /* Object fitting for responsive images */
+  object-fit: var(--img-object-fit);
+  object-position: var(--img-object-position);
+  aspect-ratio: var(--img-aspect-ratio);
+
+  /* Accessibility - Italic font for broken image alt text */
+  font-style: italic;
+
+  /* Background for loading state */
+  background-size: cover;
+  background-repeat: no-repeat;
+
+  /* Shape margin for text wrapping */
+  shape-margin: var(--spc-3);
+}
+
+figure {
+  &:has(img[alt]) {
+    --fig-display: flex;
+    --fig-p: 0.5rem;
+    --fig-bg: rgba(245, 245, 245, 0.683);
+    --fig-w: fit-content;
+    display: var(--fig-display);
+    position: relative;
+    padding: var(--fig-p);
+    background-color: var(--fig-bg);
+    max-width: var(--fig-w);
+    > figcaption {
+      position: absolute;
+      bottom: var(--fig-bottom, var(--fig-p));
+      left: var(--fig-left, var(--fig-p));
+      right: var(--fig-right, var(--fig-p));
+      padding: var(--caption-p, var(--spc-3));
+      background-color: var(--fig-bg);
+    }
+  }
+}

package/src/components/layout/_header.scss

@@ -9,24 +9,24 @@ header,
   --overlay-display: grid;
   // Overlay padding
   --overlay-padding: 2rem;
-  --overlay-w: 100%;
-  --overlay-h: 40vh;
-  --overlay-max-h: 500px;
+  --overlay-width: 100%;
+  --overlay-height: 40vh;
+  --overlay-max-height: 500px;
   --overlay-color: currentColor;
-  --overlay-content-w: 80%;
+  --overlay-content-width: 80%;
   --overlay-gap: 2rem;
   --overlay-bg: whitesmoke;
-  --overlay-px: auto;
-  --overlay-py: auto;
-  --overlay-mx: auto;
-  --overlay-my: auto;
+  --overlay-padding-inline: auto;
+  --overlay-padding-block: auto;
+  --overlay-margin-inline: auto;
+  --overlay-margin-block: auto;
 
   grid-template-areas: 'overlay';
   display: var(--overlay-display);
   place-items: var(--overlay-placement);
   align-items: var(--overlay-placement);
-  min-height: var(--overlay-h);
-  width: var(--overlay-w);
+  min-height: var(--overlay-height);
+  width: var(--overlay-width);
   color: var(--overlay-color);
   background-color: var(--overlay-bg);
   min-width: 20rem;
@@ -34,16 +34,16 @@ header,
     grid-area: overlay;
   }
   > img {
-    width: var(--overlay-w);
+    width: var(--overlay-width);
     // height: auto;
     background-size: contain;
   }
   > div,
   > section {
     --overlay-display: flex;
-    max-width: var(--overlay-content-w);
+    max-width: var(--overlay-content-width);
     padding-inline: var(--spc-4);
-    margin-inline: var(--overlay-mx);
+    margin-inline: var(--overlay-margin-inline);
     gap: var(--overlay-gap);
     text-align: center;
     p {
@@ -54,7 +54,7 @@ header,
     }
     > h1,
     > h2 {
-      line-height: var(--header-lh, 1.1);
+      line-height: var(--header-line-height, 1.1);
       font-weight: 500;
     }