Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
306 lines (210 loc) · 10.8 KB

CONTRIBUTING.md

File metadata and controls

306 lines (210 loc) · 10.8 KB

Contributing to Depression-Sensitive Web Content Support (DS-WCS)

Thank you for your interest in improving cognitive accessibility and emotional safety on the web. This document explains how to contribute effectively to this OpenCode skill.

Ways to Contribute

1. Report Missing Content Patterns

Found a problematic UX pattern not covered by the existing checklist or examples?

Open an issue and include:

  • Pattern description: What content or interaction creates barriers?
  • Context: Where does this appear? (error messages, CTAs, empty states, etc.)
  • Impact: How does it affect users with depression or cognitive differences?
  • Proposed remediation: How should it be rewritten?

Example issue:

Title: Missing pattern: countdown timers on checkout pages

Pattern: Visible countdown timer ("You have 8:32 remaining") on checkout forms
Context: E-commerce checkout flows
Impact: Creates urgency pressure that compounds executive function difficulties;
        users may make rushed, incorrect decisions or abandon the task entirely
Proposed remediation: Remove the timer, or extend to 15+ minutes with a
        non-alarming indicator (e.g. "Your cart is saved for 24 hours")

2. Add Before/After Rewrite Examples

Contribute new examples to Section A.2 of the implementation guide.

File: .opencode/skills/depression-sensitive-web-content/resources/implementation-guide.md

Where to add: After the last numbered example in Section A.2.

Required format:

**Example N: [Descriptive Title] - [Platform Type] ([General Web / Sensitive Context])**

*Original:*

[exact problematic content]


*Recommended Rewrite:*

[improved content]


*Rationale:*
- [Specific change 1 and why it improves accessibility]
- [Specific change 2 and how it reduces cognitive load]
- [Specific change 3 and how it supports emotional safety]

*Standards Mapping:*
- WCAG 2.2: [criterion number and name, e.g. 3.3.3 Error Suggestion (AA)]
- W3C COGA: [objective number and name, e.g. Objective 2: Help users avoid mistakes]
- ISO 9241-110: [principle name, e.g. Error tolerance]
- ISO/IEC 30071-1: [clause if applicable, e.g. Clause 8.2]

Content requirements:

  • Maintain a mix of general web and sensitive-context examples (healthcare, finance, job applications, wellness platforms)
  • Map each example to all four standards (WCAG 2.2, W3C COGA, ISO 9241-110, ISO/IEC 30071-1)
  • Use clinical and professional tone; avoid casual or colloquial language
  • Ensure the rationale is grounded in cognitive science or established accessibility principles

3. Expand the Audit Checklist

Add new checklist items to Section C of the implementation guide.

File: .opencode/skills/depression-sensitive-web-content/resources/implementation-guide.md

Where to add: Under the most relevant existing category (C.1–C.13), or create a new ### C.N category if the pattern does not fit existing ones.

Required format:

#### C.N.M [Item Name]

**Check:** [One-sentence description of what to look for during an audit]

**Severity:** HIGH | MEDIUM | LOW

**Examples:**
- [Concrete example of the problematic pattern]
- [Another concrete example]
- [A third example]

**Remediation:**
[Clear, specific guidance on how to fix the issue]

**Standards References:**
- WCAG [criterion number and name]
- COGA Objective [number]
- ISO 9241-110 ([principle name])
- ISO/IEC 30071-1 (Clause [number]) — include only if directly applicable

Severity definitions:

Severity Criteria
HIGH Directly causes task abandonment, emotional distress, or prevents task completion; violates WCAG Level A
MEDIUM Increases cognitive load or emotional friction; may cause abandonment; violates WCAG Level AA or ISO 9241-110 principles
LOW Reduces comfort or satisfaction; missed improvement opportunity; does not violate standards

4. Improve Standards Traceability

Help ensure that every recommendation maps accurately and completely to all four standards.

Standards used in this skill:

Standard Full Name Primary Use
WCAG 2.2 Web Content Accessibility Guidelines 2.2 Success criteria for perceivable, operable, understandable content
W3C COGA Cognitive and Learning Disabilities Accessibility Supplemental Guidance Objectives for users with cognitive differences
ISO 9241-110 Ergonomics of Human-System Interaction: Dialogue Principles Seven principles for effective human-system dialogue
ISO/IEC 30071-1 Information Technology - User Interface Accessibility Governance, policy, and process requirements

When reviewing or improving standards mappings:

  • Verify WCAG success criteria numbers and conformance levels (A, AA, AAA)
  • Reference specific COGA objectives by number (1–4) and pattern where possible
  • Use ISO 9241-110 principle names consistently: Self-descriptiveness, Controllability, Conformity with user expectations, Suitability for the task, Error tolerance, Suitability for individualization, Suitability for learning
  • Reference ISO/IEC 30071-1 clauses (7.x, 8.x, 9.x) only where directly applicable

Reference sources:

5. Improve Documentation

Help make the skill easier to discover, understand, and use.

Areas that welcome improvement:

  • README.md: Additional usage examples, installation troubleshooting, FAQ section
  • SKILL.md: Workflow clarity, edge case handling, integration examples
  • FORK_INSTRUCTIONS.md: Platform-specific customization notes
  • Implementation guide: Improved section introductions, cross-references between sections

Pull Request Process

Before You Start

  1. Fork the repository to your own GitHub account
  2. Clone your fork locally: 
    git clone https://github.com/YOUR-USERNAME/depression-sensitive-web-content.git
cd depression-sensitive-web-content
  3. Create a feature branch with a descriptive name: 
    git checkout -b feature/add-mobile-form-examples
# or
git checkout -b fix/standards-mapping-c3-5

Making Changes

Follow the formats described above. When ready:

git add .
git commit -m "Add 2 mobile form validation examples

- Example 16: Mobile inline validation with haptic feedback context
- Example 17: Mobile password strength indicator

Both examples include full WCAG 2.2, COGA, ISO 9241-110 mappings."

Testing Locally

Before submitting, verify the skill works in OpenCode:

# Copy to your global skills directory
cp -r . ~/.config/opencode/skills/depression-sensitive-web-content

# Open a project in OpenCode and test
# Ask: "Audit this content for depression-sensitive issues"
# Confirm the skill loads and applies your new content

Submitting the Pull Request

  1. Push your branch to your fork: 
    git push origin feature/add-mobile-form-examples
  2. Go to your fork on GitHub and click Compare & pull request
  3. Use this description template:
## Summary

[1–3 sentences describing what this PR adds or fixes]

## Changes

- [Specific change 1]
- [Specific change 2]

## Standards Coverage

- [ ] All new content maps to WCAG 2.2 (verified criterion numbers)
- [ ] All new content maps to W3C COGA (verified objective numbers)
- [ ] All new content maps to ISO 9241-110 (verified principle names)
- [ ] ISO/IEC 30071-1 referenced where directly applicable

## Testing

- [ ] Skill loads in OpenCode without errors
- [ ] New examples/checklist items follow the required format
- [ ] Tone is clinical/professional throughout
- [ ] No medical advice or diagnosis language present

Code of Conduct

This project addresses mental health, cognitive differences, and emotional safety in web interfaces. All contributions must adhere to the following standards.

Required

Maintain clinical and professional tone

  • Use evidence-based language
  • Cite specific standards or research where applicable
  • Avoid colloquialisms, casual phrasing, and informal register

Include non-clinical disclaimers where appropriate

  • Be explicit that this is a UX and content tool, not a clinical resource
  • Direct users to qualified healthcare professionals for mental health concerns

Avoid medical advice or diagnosis

  • Do not suggest clinical interventions for users with depression
  • Do not diagnose conditions based on content patterns
  • Focus entirely on interface and content design

Use person-first, non-stigmatizing language

  • Use "users with depression" rather than "depressed users"
  • Use "cognitive differences" in preference to value-laden alternatives
  • Frame all guidance as supportive, not remedial

Respect diverse user needs

  • Consider international and cross-cultural contexts
  • Avoid culturally specific assumptions in examples
  • Support multiple assistive technologies where relevant

Not Permitted

  • Medical advice or clinical guidance of any kind
  • Stigmatizing language about mental health conditions
  • Content lacking evidence-based or standards-aligned rationale
  • Examples that reproduce harmful UI patterns without clear remediation

Contributions that do not meet these standards will be declined with specific, constructive feedback.

Review Process

  1. Format check: Maintainer verifies the contribution follows the required format
  2. Standards accuracy: Criterion numbers, objective references, and principle names are verified
  3. Tone review: Contribution is checked for clinical/professional tone and non-clinical compliance
  4. Feedback: Specific, actionable feedback is provided within 7 days
  5. Approval: Approved PRs are merged and contributors are credited in the release notes

Questions

Not sure whether your contribution fits? Open a discussion issue before writing code. Prefix the title with [Discussion], describe your idea, and ask for feedback. This saves time for everyone.

Need help with standards mapping? Open your PR as a draft and leave a comment asking specifically which standards apply to your addition. The maintainers will provide guidance before you finalize the work.

Technical issues with OpenCode skill development? See the OpenCode documentation for skill structure and YAML frontmatter requirements.

Thank you for contributing to more inclusive, emotionally safe digital experiences. Every improvement helps reduce cognitive and emotional barriers for users around the world.