Skip to content

FOUNDATION_CSS_IMPROVEMENT_PROPOSAL.md

Latest commit

 

History

History
208 lines (164 loc) · 6 KB

FOUNDATION_CSS_IMPROVEMENT_PROPOSAL.md

File metadata and controls

208 lines (164 loc) · 6 KB
Raw

Proposal: Baseline UX/UI & Styling Enhancements for foundation.css

To: Team Lead
From: Antigravity AI Coding Assistant
Date: August 5, 2026
Subject: Audit and Proposed Enhancements for Default HTML Element Styling in src/themes/foundation.css

Executive Summary

Rtifact's core product goal is turning agent-authored JSX into portable, human-readable, and visually consistent HTML artifacts. While our themes provide rich Ant Design tokens and Tailwind utility integration, baseline HTML elements rendered without custom Tailwind classes currently rely on standard browser defaults.

Following our recent enhancement to inline code and kbd spacing in src/themes/foundation.css, a audit of the remaining unstyled standard HTML elements identified several baseline UX/UI gaps.

This proposal outlines 5 focused styling enhancements for src/themes/foundation.css to ensure that raw HTML elements generated by AI agents render with high visual quality, proper responsive boundaries, and accessible contrast out of the box.

Identified Gaps & Proposed Enhancements

1. 📊 Native HTML Tables (<table>, <th>, <td>)

  • Current State: foundation.css only sets table { border-color: var(--border); }.
  • Issue: Un-styled native HTML tables render with uncollapsible borders, zero cell padding, and browser-default alignment, looking unpolished compared to Ant Design tables.
  • Proposed Enhancement: 
    table {
  width: 100%;
  border-collapse: collapse;
  text-align: start;
}
th {
  padding: 0.6em 0.8em;
  border-bottom: 2px solid var(--border);
  font-weight: var(--heading-weight);
  text-align: start;
}
td {
  padding: 0.6em 0.8em;
  border-bottom: 1px solid var(--border);
}

2. 🖼️ Responsive Embedded Media (<img>, <video>, <svg>, <canvas>)

  • Current State: No global responsive constraints on embedded media elements.
  • Issue: If an AI agent includes an <img>, <svg>, <video>, or <canvas> without explicit Tailwind width utility classes (e.g., w-full), large media will overflow its parent container or viewport.
  • Proposed Enhancement: 
    img,
video,
canvas,
svg {
  max-width: 100%;
  height: auto;
  vertical-align: middle;
}

3. ⌨️ Tactile Keyboard Keycaps (<kbd>)

  • Current State: <kbd> shares identical rules with :not(pre) > code (background: var(--code) and border-radius: var(--theme-radius-sm)).
  • Issue: Keyboard shortcuts (<kbd>Cmd</kbd> + <kbd>K</kbd>) look indistinguishable from inline code snippets (<code>fn()</code>).
  • Proposed Enhancement: 
    kbd {
  border: 1px solid var(--border);
  box-shadow: 0 1px 1px rgba(0, 0, 0, 0.1);
  font-size: 0.82em;
}

4. 🎛️ Form Controls & Unstyled Inputs

  • Current State: button:not([class]), input:not([class]), select:not([class]), and textarea:not([class]) set height, border, background, and font, but lack basic padding, cursor behavior, and resize rules.
  • Issue:
    • input and select text touches the left/right border due to zero padding-inline.
    • button and select retain default arrow cursors instead of cursor: pointer.
    • textarea forces min-height: var(--control-height) without padding or resize: vertical.
  • Proposed Enhancement: 
    input:not([class]),
select:not([class]) {
  padding-inline: 0.75rem;
}

textarea:not([class]) {
  padding: 0.5rem 0.75rem;
  resize: vertical;
}

button:not([class]),
select:not([class]) {
  cursor: pointer;
}

5. 💡 Text Highlighting (<mark>) & Disclosures (<details> / <summary>)

  • Current State: <mark>, <details>, and <summary> use browser default styles.
  • Issue:
    • <mark> renders with browser default neon yellow (#ffff00), breaking dark theme contrast.
    • <summary> disclosure headers lack affordance indicators (cursor: pointer).
  • Proposed Enhancement: 
    mark {
  background: var(--warning-background);
  color: var(--warning-foreground);
  border-radius: var(--theme-radius-sm);
  padding: 0.1em 0.3em;
}

summary {
  cursor: pointer;
  font-weight: var(--heading-weight);
}

Complete Proposed CSS Addition for foundation.css

/* Proposed additions to @layer base in src/themes/foundation.css */

img,
video,
canvas,
svg {
  max-width: 100%;
  height: auto;
  vertical-align: middle;
}

kbd {
  border: 1px solid var(--border);
  box-shadow: 0 1px 1px rgba(0, 0, 0, 0.1);
  font-size: 0.82em;
}

table {
  width: 100%;
  border-collapse: collapse;
  text-align: start;
}

th {
  padding: 0.6em 0.8em;
  border-bottom: 2px solid var(--border);
  font-weight: var(--heading-weight);
  text-align: start;
}

td {
  padding: 0.6em 0.8em;
  border-bottom: 1px solid var(--border);
}

mark {
  background: var(--warning-background);
  color: var(--warning-foreground);
  border-radius: var(--theme-radius-sm);
  padding: 0.1em 0.3em;
}

summary {
  cursor: pointer;
  font-weight: var(--heading-weight);
}

input:not([class]),
select:not([class]) {
  padding-inline: 0.75rem;
}

textarea:not([class]) {
  padding: 0.5rem 0.75rem;
  resize: vertical;
}

button:not([class]),
select:not([class]) {
  cursor: pointer;
}

Impact Analysis

  1. Non-Breaking: All rules are placed in @layer base or scoped with :not([class]), ensuring they do not override Tailwind utility classes or custom component styling.
  2. Theme Contract Compliance: Uses existing theme CSS variables (var(--border), var(--warning-background), var(--heading-weight), etc.), respecting both light and dark presets automatically.
  3. Agent Efficiency: AI agents generating standard HTML/JSX don't need to append verbose Tailwind utilities to basic tables, keycaps, or form inputs to achieve acceptable visual quality.

Action Requested

Please review the proposed enhancements. Upon approval, unit tests and integration verification will be updated alongside the foundation.css changes.