Skip to content

AGENTS.md

Latest commit

 

History

History
247 lines (185 loc) · 7.52 KB

AGENTS.md

File metadata and controls

247 lines (185 loc) · 7.52 KB
type ai-agent-guide
framework Accessibility-Statement-Library
language Swift
ui-framework SwiftUI
platforms
iOS
min-deployment iOS 15.0

Accessibility Statement Library iOS Framework - AI Agent Guide

This file provides guidance to AI coding agents when working with code in this repository or with Accessibility Statement Library iOS products.

Project Overview

Accessibility Statement Library is a simple library which provides a SwiftUI view to display an accessibility statement for legal reasons. It processes an XML file generated by La va11ydette, another Orange open source product. The aim is to be compliant with local laws and display how much the target app is compliant with accessibility rules like WCAG. Developers use the XML file to define the view, and can define additional HTML file to display more details. This file can be hosted in the app and displayed in a webview, or outside the app displayed in a webview or not in that case. The library is open source under license Aapche 2.0.

Vocabulary

  • statement: A declaration, a statement, with legal information about the company and scores
  • theme: A style to apply to the view (Orange, Sosh, Innovation Cup)

Code formating

The source code is formatted for Swift 5.7. Configuration of formater is in .swiftformat and linter in .swiftlint.

Architecture guidelines

  • SwiftUI is the default UI paradigm - embrace its declarative nature
  • Avoid legacy UIKit patterns and unnecessary abstractions
  • Focus on simplicity, clarity, and native data flow
  • Let SwiftUI handle the complexity - don't fight the framework
  • Organize by components, keeps things isolated
  • Keep related code together in the same file when appropriate
  • Use extensions to organize large files
  • Follow Swift naming conventions consistently

Build verification process

IMPORTANT: When editing code, you MUST:

  1. Format the sources
  2. Build the project after making changes
  3. Fix any compilation errors before proceeding
  4. Run the tests
  5. Run the linter and fix any warnings and errors

Best practices

DO

  • Write documentation in Swift DocC format for public API
  • Use Swift's type system for safety
  • Use public modifier only when needed, prefer internal or private
  • IMPORTANT: The project supports iOS 26 SDK while maintaining iOS 15 as the minimum deployment target. Use #available checks when adopting iOS 15+ APIs.
  • IMPORTANT: The project runs for iOS / iPadOS
  • If a third party dependency is added or updated, update the Software Bill of Material
  • Apply Clean Code, DRY, SOLID and TDD principes

DON'T

  • Add abstraction layers without clear benefit
  • Use Combine for simple async operations
  • Overcomplicate simple features
  • Use UIKit except for some specific API related to accessibility if needed

Development requirements

  • Minimum Swift 5.7
  • Xcode 26.2 or later
  • Minimum deployment: iOS 15.0, iPad0S 15.0
  • Apple Developer account for device testing

Building commands

Building Swift Package

To build the Swift Package:

swift build

Run tests

To run the unit tests on the Swift Package:

swift test

Check dead code

To check for dead code:

brew install periphery
cd scripts
./check-dead-code.sh

Format the sources

To format the source code:

brew install swiftformat
cd scripts
./run-format.sh

Run linter

To run the linter:

brew install swiftlint
cd scripts
./run-lint.sh

SBOM update

To update the Software Bill of Materials:

brew install syft
brew tap anchore/grype
brew install grype
cd scripts
./update-sbom.sh

Review guidelines

  • Check if sources are formatted
  • Run linter, no error must appear
  • Run tests, they must all pass
  • Check if there is dead coden and leave a comment saying the elements which seem toi be dead / not used
  • Build documentation, no error must appear
  • Check leaks, no leak must appear
  • Check if functions are too long or too complicated, complexity must be low
  • Check if the commit has been designed-off (i.e. DCO appplied) by all commits authors

How to use Accessibility Statement Lib iOS framwork

Basic setup

import DeclarationAccessibility
import SwiftUI

struct AccessibilityStatementView: View {

    let detailsPageURL: URL

    init() {
        // Load from app bundle a "accessibilty_detail.html" file
        guard let detailsPageURL = Bundle.main.url(forResource: "accessibility_detail", withExtension: "html") else {
            fatalError("Unable to find accessibility_detail.html in resources")
        }

        self.detailsPageURL = detailsPageURL
    }

    var body: some View {
        VStack {
            // Supposed to have "accessibility_result" XML file in app bundle
            // Here load a local HTML page ("accessibility_detail" HTML file in app bundle), forced to be in webview
            StatementView(xmlFileName: "accessibility_result", theme: .orange, localURL: detailsPageURL.absoluteString)
        }
    }
}

or with OUDS library:

import DeclarationAccessibility
import OUDSSwiftUI
import SwiftUI

struct AccessibilityStatementPage: View {

    let detailsPageURL: URL
    @Environment(\.theme) var theme

    init() {
        guard let detailsPageURL = Bundle.main.url(forResource: "accessibility_detail", withExtension: "html") else {
            OL.fatal("Unable to find accessibility_detail.html in resources")
        }

        self.detailsPageURL = detailsPageURL
    }

    var body: some View {
        VStack {
            StatementView(xmlFile: "accessibility_result", localUrl: detailsPageURL.absoluteString, theme: theme)
        }
    }
}

Import the product

Import the dedicated library from the Swift Package

import DeclarationAccessibility

Use local detailed HTML file

Supposing accessibility_result is the XML file generated from La va11ydette, for the orange theme, use a local HTML file with details about the statement:

StatementView(xmlFile: "accessibility_result", theme: .orange, localUrl: absoluteStringUrlToLocalFile)

Use external detailed HTML file

Supposing accessibility_result is the XML file generated from La va11ydette, for the sosh theme, use an HTML page with details about the statement outside on the web, displayed in a webview:

StatementView(xmlFile: "accessibility_result", theme: .orange, remoteUrl:  "https://a11y-guidelines.orange.com/fr/", useWebView: true)

and displayed outside the app in browser:

StatementView(xmlFile: "accessibility_result", theme: .orange, remoteUrl:  "https://a11y-guidelines.orange.com/fr/", useWebView: false)
// Or same thing
StatementView(xmlFile: "accessibility_result", theme: .orange, remoteUrl:  "https://a11y-guidelines.orange.com/fr/")

Use of Orange Unified Design System library

If you use the OUDS library, it is possible to give an OUDSTheme object to the StatementView so as to apply on it predefined themes (like instances of OrangeTheme, OrangeBusinessToolsTheme, SoshTheme and WireframeTheme) or any local theme.

For example, with a local file:

StatementView(xmlFile: "accessibility_result", localUrl: absoluteStringUrlToLocalFile, theme: someOudsTheme)

Or with an external file:

StatementView(xmlFile: "accessibility_result", remoteUrl:  "https://a11y-guidelines.orange.com/fr/", useWebView: true, theme: someOudsTheme)