Naomi's VSCode Themes

Naomi’s VSCode Themes (hereinafter the “Application”) is a Visual Studio Code extension that provides a curated collection of custom colour themes designed to enhance the coding experience with aesthetically pleasing colour schemes. The Application currently offers four distinct themes: Ocean Breeze, Sakura Dreams, Sakura Dreams (Dark), and Trans Pride.

1. User Documentation

This section is for those interacting with a live instance of the Application.

1.1. Overview

Naomi’s Themes is a VSCode extension that provides custom colour themes for your code editor. Each theme has been carefully crafted with specific colour palettes to create visually appealing and comfortable coding environments.

1.2. Available Themes

The Application includes the following themes:

• Ocean Breeze: A dark theme featuring soothing teal and cyan colours reminiscent of ocean waves, designed for extended coding sessions with reduced eye strain
• Sakura Dreams: A light theme inspired by cherry blossoms with soft, pastel colours
• Sakura Dreams (Dark): A dark variant of the Sakura Dreams theme, maintaining the cherry blossom aesthetic while providing a darker background
• Trans Pride: A light theme celebrating trans pride with a carefully selected colour palette

1.3. Installation

1. Open Visual Studio Code
2. Navigate to the Extensions view (Ctrl+Shift+X / Cmd+Shift+X)
3. Search for “Naomi’s Themes” by SpellWare
4. Click “Install”

1.4. Activating a Theme

After installation:

1. Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
2. Type “Preferences: Color Theme”
3. Select your desired theme from the list:
   • Ocean Breeze
   • Sakura Dreams
   • Sakura Dreams (Dark)
   • Trans Pride

1.5. Requirements

• Visual Studio Code version 1.96.4 or higher

1.6. Support and Feedback

If you encounter any issues or have feedback:

• Post in the #bug-reports or #feature-requests forum channels on our Discord community
• Contact via Chat Server: https://chat.spellware.dev
• Email: [email protected]

2. Technical Documentation

This section is for those interested in running their own instance of the Application.

2.1. Architecture

The Application is structured as a standard VSCode extension with the following components:

• Theme Definitions: JSON files located in the themes/ directory, each defining colour schemes for UI elements and syntax highlighting
• Extension Manifest: package.json containing metadata and theme contributions
• Assets: icon.png for the extension icon

2.2. Project Structure

vscode-themes/
├── themes/
│   ├── ocean-breeze.json
│   ├── sakura-dreams.json
│   ├── sakura-dreams-dark.json
│   └── trans-pride.json
├── package.json
├── icon.png
├── README.md
├── LICENSE.md
├── CONTRIBUTING.md
├── CODE_OF_CONDUCT.md
├── PRIVACY.md
├── TERMS.md
└── SECURITY.md

2.3. Local Development Setup

Prerequisites

• Node.js and npm installed
• Visual Studio Code installed
• vsce (Visual Studio Code Extension Manager) installed globally

Setup Steps

1. Clone the repository:

   git clone https://github.com/spellware/vscode-themes.git
   cd vscode-themes

2. Install vsce if not already installed:

   npm install -g @vscode/vsce

3. Package the extension:

   npm run package

4. Install the packaged extension in VSCode:

   • Open VSCode
   • Go to Extensions view
   • Click the ”…” menu
   • Select “Install from VSIX…”
   • Choose the generated .vsix file

2.4. Creating a Theme

Each theme is defined in a JSON file with the following structure:

{
  "name": "Theme Name",
  "type": "dark" or "light",
  "colours": {
    // UI element colours
  },
  "tokenColors": [
    // Syntax highlighting rules
  ]
}

Key sections:

• colours: Defines colours for editor UI elements (background, foreground, sidebar, statusbar, etc.)
• tokenColors: Array of rules defining syntax highlighting colours based on TextMate scopes

For example, see themes/ocean-breeze.json at lines 1-373.

2.5. Building and Packaging

The package script is configured in package.json at lines 38-39:

npm run package

This command:

• Packages the extension into a .vsix file
• Sets the base content and images URLs to the repository

2.6. Publishing

The extension is published by SpellWare to the VSCode Marketplace. The publisher configuration is defined in package.json at line 10.

2.7. Version Management

Current version: 2.3.0 (as defined in package.json at line 5)

Version history (from git commits):

• 2.2.0: Current release
• 2.1.0: Added dark mode and updated source links
• 2.0.0: Major version update

3. Legal Documentation

This section is for expansions to our legal policies specific to the Application.

3.1. License

The Application is licensed under Naomi Carrigan’s global software licence, available at: https://docs.spellware.dev/#/license

Copyright is held by Naomi Carrigan.

Reference: LICENSE.md at lines 1-5

3.2. Privacy Policy

The Application adheres to the privacy policy documented at: https://docs.spellware.dev/#/privacy

As a VSCode theme extension, the Application:

• Does not collect any user data
• Does not transmit any information externally
• Operates entirely locally within VSCode

Reference: PRIVACY.md at lines 1-3

3.3. Terms of Service

The Application is governed by the Terms of Service available at: https://docs.spellware.dev/#/terms

Reference: TERMS.md at lines 1-3

3.4. Security Policy

Security policies and vulnerability reporting procedures are documented in SECURITY.md.

3.5. Intellectual Property

All themes, colour schemes, and design elements are copyright of Naomi Carrigan. The theme names “Ocean Breeze,” “Sakura Dreams,” and “Trans Pride” are part of this intellectual property.

4. Contributing Documentation

This section is for documentation related to contributing to the Application’s codebase.

4.1. Contributing Guidelines

Complete contributing guidelines are available at: https://docs.spellware.dev/#/contributing

Reference: CONTRIBUTING.md at lines 1-3

4.2. Code of Conduct

Before participating in the project, please review the Code of Conduct at: https://github.com/spellware/vscode-themes/blob/main/CODE_OF_CONDUCT.md

The project maintains a welcoming and inclusive environment for all contributors.

Reference: README.md at lines 13-15

4.3. How to Contribute

Reporting Issues

1. Check existing posts in the #bug-reports or #feature-requests forum channels on our Discord community
2. Post in the appropriate forum channel with:
   • Clear description of the problem or suggestion
   • Steps to reproduce (for bugs)
   • Expected vs. actual behaviour
   • VSCode version and operating system

Submitting Pull Requests

1. Fork the repository
2. Create a feature branch from main
3. Make your changes:
   • For new themes: Add a new JSON file in themes/ directory
   • For theme modifications: Edit the respective JSON file
   • Update package.json if adding a new theme
4. Test your changes locally by packaging and installing the extension
5. Commit your changes with clear, descriptive commit messages
6. Submit a pull request to the main branch
7. Await review from the maintainers

Theme Contribution Guidelines

When contributing a new theme:

1. Ensure the theme has a unique name and aesthetic
2. Define both colours and tokenColors sections comprehensively
3. Test the theme with multiple programming languages
4. Ensure sufficient contrast for accessibility
5. Add the theme entry to package.json under contributes.themes
6. Specify the correct uiTheme base (“vs” for light, “vs-dark” for dark)

Example theme entry in package.json:

{
  "label": "Your Theme Name",
  "uiTheme": "vs-dark",
  "path": "./themes/your-theme-name.json"
}

Reference: package.json at lines 14-36

4.4. Development Standards

File Naming Conventions

• Theme files: Use kebab-case (e.g., ocean-breeze.json, sakura-dreams-dark.json)
• Theme files should be placed in the themes/ directory

JSON Formatting

• Use 2-space indentation
• Ensure valid JSON syntax
• Include all required theme properties

Color Guidelines

• Use hex colour codes (e.g., #012a22)
• Consider accessibility and contrast ratios
• Test colours in both day and night lighting conditions
• Document colour inspiration or theme concept if applicable

4.5. Testing

Before submitting:

1. Package the extension locally using npm run package
2. Install the VSIX file in a clean VSCode instance
3. Test the theme with multiple file types:
   • JavaScript/TypeScript
   • Python
   • Rust
   • HTML/CSS
   • Markdown
4. Verify UI elements (sidebar, statusbar, tabs, etc.) are properly styled
5. Check for colour contrast issues

4.6. Release Process

Releases are managed by the project maintainer (Naomi Carrigan). The typical release process:

1. Update version in package.json
2. Commit version changes
3. Create a git tag for the version
4. Run npm run package to generate the VSIX file
5. Publish to VSCode Marketplace (maintainer only)

Recent release pattern (from git history):

• Version bumps follow semantic versioning
• Releases are tagged in git
• Each release includes descriptive commit messages

4.7. Community and Communication

• Issues and discussions: Post in the #bug-reports or #feature-requests forum channels on our Discord community
• Chat Server: https://chat.spellware.dev
• Email: [email protected]
• Homepage: https://spellware.dev

4.8. Recognition

Contributors are valued members of the project. Significant contributions may be recognised in release notes or project documentation.