CSS Assistant

BETA RELEASE: CSS Assistant is currently in beta. All feedback is welcome and appreciated.

An AI-powered VS Code extension that helps web developers, particularly those who are blind or visually impaired, create visually appealing websites through accessible CSS assistance.

Why CSS Assistant Exists

CSS is inherently visual, making it challenging for blind and visually impaired developers to create aesthetically pleasing websites. CSS Assistant bridges this gap by providing rich, conversational descriptions of CSS code, color contrast analysis, and comprehensive reports that translate visual concepts into accessible language.

As a blind developer, I created this extension to solve the unique challenges we face:

• Understanding how colors interact and appear to sighted users
• Ensuring proper contrast ratios for accessibility
• Visualizing layouts and spacing without being able to see them
• Receiving feedback on the visual impact of CSS changes

CSS Assistant uses natural, conversational language to describe visual elements in terms that are meaningful regardless of visual ability, helping blind developers create websites that look good to everyone.

Features

All features work with CSS, SCSS, Less, and HTML files. When using HTML files, CSS Assistant automatically extracts styles from:

• Inline <style> tags
• Style attributes on elements
• And identifies linked stylesheets

How It Helps Blind Developers

• Conversational Descriptions: Instead of technical jargon, CSS Assistant describes visual elements using everyday language and relatable comparisons
• Emotional Context: Explains how colors and layouts might feel emotionally to users, providing context beyond just technical specifications
• Spatial Relationships: Uses clear, everyday terms to describe how elements relate to each other spatially
  • Explains layouts using concepts like "above," "below," "side-by-side," or "stacked"
  • Describes distances in relatable terms like "finger width" or "thumb width" apart
  • Clarifies how elements align (centered, left-aligned, right-aligned)
  • Explains how layouts change across different screen sizes
• Screen Reader Friendly: All responses are structured with proper headings and organized information for optimal screen reader navigation

Prerequisites

• VS Code 1.60.0 or higher
• GitHub Copilot extension installed and activated
• GitHub Copilot Chat extension installed and activated

Installation

1. Open Visual Studio Code
2. Go to the Extensions view by clicking on the Extensions icon in the Activity Bar or pressing Ctrl+Shift+X
3. Search for "CSS Assistant"
4. Click the Install button for CSS Assistant
5. Once installed, reload VS Code when prompted

Detailed Feature Documentation

1. Generate Full CSS Report

Command: CSS Assistant: Generate Full CSS Report

What it does: Provides a comprehensive analysis of your CSS file and workspace, combining visual description and color contrast analysis into a single report.

When to use it:

• When starting work on an existing CSS codebase you're unfamiliar with
• When you want a complete understanding of how your CSS appears visually
• Before finalizing a CSS file to ensure it meets accessibility standards
• When you need detailed recommendations for improving your CSS
• When working with HTML files to analyze embedded styles and linked stylesheets

The report includes:

1. Visual Description:

   • Overall visual impression and layout
   • Detailed color descriptions with emotional context
   • Typography explanations in relatable terms
   • Spacing and positioning described using everyday spatial concepts
   • Interactive element behaviors explained conversationally

2. Color Contrast Analysis:

   • Identification of all colors in your CSS
   • Analysis of primary, secondary, text, and background colors
   • Contrast ratio calculations between color combinations
   • WCAG compliance evaluation (AA and AAA standards)
   • Alternative color suggestions for non-compliant combinations

3. Summary & Recommendations:

   • Strengths of the current CSS
   • Prioritized list of improvements
   • Specific code examples for implementing changes

2. Describe Current CSS File

Command: CSS Assistant: Describe Current CSS File

What it does: Provides a focused description of what your current CSS file would look like visually, using conversational language and relatable comparisons.

When to use it:

• When you want to understand the visual impact of a specific CSS file
• When making changes to a CSS file and want to confirm the visual result
• When you need a quick visual description without the full analysis
• When focusing on the aesthetic aspects rather than technical evaluation
• When working with HTML files to understand the visual impact of embedded styles

3. Describe Workspace CSS

Command: CSS Assistant: Describe Workspace CSS

What it does: Analyzes all CSS files in your workspace to provide a holistic understanding of your site's visual design.

When to use it:

• When working with multiple CSS files that together create your site's appearance
• When you need to understand how different CSS components interact
• When starting work on an existing project with multiple stylesheets
• When you want to ensure consistency across your entire site's design

4. Color Contrast Analyzer

Command: CSS Assistant: Color Contrast Analyzer

What it does: Provides specialized analysis of color combinations to ensure they meet WCAG accessibility standards

When to use it:

• When selecting colors for your website
• When checking if your existing colors meet accessibility standards
• When you need to ensure your site is usable by people with visual impairments
• When you want to understand how colors interact and appear to users

5. Open Chat

Command: CSS Assistant: Open Chat

What it does: Opens a direct chat interface where you can ask specific questions about CSS and web design.

When to use it:

• When you have specific CSS questions not covered by the other commands
• When you need guidance on implementing a particular visual effect
• When you want to learn more about CSS concepts in an accessible way
• When you need help troubleshooting CSS issues
• When you need to understand how specific visual scenarios appear, such as "How does a black background affect readability?"
• When you need to ask direct questions about your CSS like "What color is my background?" or "Are my headings using a serif or sans-serif font?"

Example questions you can ask:

• "How do I create a responsive card layout that works well for screen readers?"
• "Explain how flexbox works in terms I can understand without seeing it"
• "What's the difference between em, rem, and px units and when should I use each?"
• "How can I create an accessible dropdown menu with CSS and minimal JavaScript?"
• "Describe how CSS animations feel to users and how to make them accessible"
• "If my background is black, what text colors would work best for accessibility?"
• "Is my background color too dark for good readability?"
• "What color are my headings in this CSS file?"
• "Does this CSS create a high-contrast or low-contrast design?"
• "How would this layout be perceived by users with color blindness?"

The Open Chat mode is particularly valuable when you need to understand specific visual scenarios that you cannot see yourself. For example, asking about how a black background affects readability, color combinations, or overall user experience allows you to make informed design decisions without relying on visual feedback. The assistant will provide detailed, conversational descriptions that translate visual concepts into accessible language, helping you understand the implications of your design choices.

You can ask direct questions about your current CSS file, such as "What color is my background?" or "What font is being used for paragraphs?" to quickly get information about specific visual aspects without having to interpret the CSS code yourself.

How CSS Assistant Translates Visual Concepts

CSS Assistant uses several techniques to make visual concepts accessible to blind developers:

Conversational Language

Instead of technical descriptions, CSS Assistant uses everyday language that doesn't require sight to understand:

Technical CSS:

.button {
  background-color: #3498db;
  color: white;
  padding: 10px 15px;
  border-radius: 5px;
  box-shadow: 0 2px 4px rgba(0,0,0,0.2);
}

CSS Assistant Description:

The button has a vibrant sky blue background (hex code #3498db) that feels fresh and inviting, like a clear summer sky. The text is crisp white, creating a strong contrast that makes it very readable. The button has a comfortable amount of padding—about the width of your fingertip—giving it room to breathe. The corners are gently rounded, softening the appearance and making it feel more approachable than if it had sharp corners. There's also a subtle shadow beneath the button, making it appear to float slightly above the page, which gives it a satisfying three-dimensional quality.

Emotional and Sensory Context

CSS Assistant describes the emotional impact and sensory associations of visual elements:

This shade of red (#e74c3c) feels energetic and attention-grabbing, like a stop sign or an alert notification. It creates a sense of urgency and would likely draw the user's eye immediately when scanning the page. When used for error messages, it effectively communicates importance and the need for attention.

Spatial Relationships Using Everyday Terms

CSS Assistant explains layouts and positioning using everyday spatial concepts:

The navigation menu sits at the very top of the page, spanning the full width like a horizontal bar. Below it, there's a large hero image that takes up about half of the initial screen space. The main content is arranged in three columns side by side, each taking up roughly equal space, with about a finger's width of space between them. When viewed on a mobile phone, these columns would stack on top of each other, with the most important content at the top.

The sidebar is positioned to the right of the main content area, taking up about 1/4 of the screen width. It contains widgets that are stacked vertically, each separated by about the height of a line of text. The footer sits at the very bottom of the page, spanning the full width, with navigation links arranged in a horizontal row and centered in the available space.

Comparative Sizing

CSS Assistant uses relatable comparisons for sizes rather than just pixel values:

The main heading is quite large—about twice the size of the normal paragraph text—making it stand out prominently. The subheadings are about halfway between the size of the main heading and the paragraph text, creating a clear visual hierarchy that guides the reader through the content in a logical order.

Usage Workflow Examples

Scenario 1: Starting a New Project

1. Create your initial CSS files
2. Use CSS Assistant: Generate Full CSS Report to get a comprehensive understanding of your starting point
3. Make adjustments based on the recommendations
4. Use CSS Assistant: Color Contrast Analyzer to ensure your color choices are accessible
5. Continue iterating, using the chat feature for specific questions

Scenario 2: Working on an Existing Project

1. Use CSS Assistant: Describe Workspace CSS to understand the overall visual design
2. Open specific CSS files and use CSS Assistant: Describe Current CSS File to understand each component
3. Make targeted improvements based on the descriptions
4. Use CSS Assistant: Generate Full CSS Report before finalizing to ensure accessibility

Scenario 3: Focusing on Accessibility

1. Use CSS Assistant: Color Contrast Analyzer to check all color combinations
2. Address any contrast issues identified
3. Use CSS Assistant: Generate Full CSS Report to identify other accessibility concerns
4. Use the chat feature to ask specific questions about making particular elements more accessible

Configuration

1. Open VS Code settings (File > Preferences > Settings)
2. Search for "CSS Assistant"
3. Select your preferred detail level for responses:
   • Basic: Shorter, more concise descriptions
   • Medium: Balanced descriptions with essential details (default)
   • Detailed: Comprehensive descriptions with extensive details

How It Works

This extension uses GitHub Copilot to provide intelligent CSS assistance with a focus on accessibility. It doesn't require any API keys as it leverages your existing GitHub Copilot subscription. The extension sends carefully crafted prompts to Copilot that emphasize conversational, accessible descriptions and formats the responses to be screen reader friendly.

Important Disclaimer

AI Limitations: While CSS Assistant provides valuable insights and assistance, it is not a substitute for human judgment and expertise:

• Color Contrast Analysis: The AI-powered color contrast analysis is a helpful tool but should not replace human evaluation for critical accessibility compliance. Always verify important accessibility features with human testers, especially for applications requiring strict WCAG compliance.

• CSS Recommendations: The suggestions provided by CSS Assistant are based on general best practices and AI analysis. Your specific project requirements, brand guidelines, or user needs may require different approaches. Always use your professional judgment when implementing recommendations.

• Visual Descriptions: The AI provides descriptions based on common interpretations of visual elements, but individual perceptions may vary. When designing for specific audiences, consider gathering direct feedback from representative users.

CSS Assistant is designed to be a helpful tool in your development workflow, not to replace human creativity, expertise, or accessibility testing.

Troubleshooting

If you encounter any issues with the extension:

1. Ensure GitHub Copilot and GitHub Copilot Chat extensions are installed and properly activated
2. Check that you have an active GitHub Copilot subscription
3. Try reloading VS Code (File > Reload Window)
4. If commands don't appear in the Command Palette, try uninstalling and reinstalling the extension

Release Notes

0.0.0

• Initial release of CSS Assistant with focus on accessibility for blind developers
• Added comprehensive CSS report functionality
• Enhanced color contrast analysis with conversational descriptions