DEV Community: hiro

AI Utilization Guidelines for Continuous Engineer Growth

hiro — Sat, 26 Jul 2025 05:28:40 +0000

AI Utilization Guidelines for Continuous Engineer Growth

Introduction

AI tools are rapidly becoming an integral part of modern development environments, making daily coding tasks more efficient and convenient. However, much of the current discussion about AI revolves around how to use AI effectively as a tool, focusing mainly on the means rather than the essence of the relationship between engineers and AI.

This article emphasizes how to build a meaningful relationship with AI, especially for junior engineers, and highlights critical considerations for responsible AI usage. Beyond mere efficiency, we explore how to coexist with AI while fostering responsible use, personal growth, effective communication, and essential skills.

Four Principles for Leveraging AI Without Hindering Growth

To use AI effectively while ensuring continuous growth, it is crucial to focus on four principles: responsibility and verification, balancing personal growth, communication, and acquiring the necessary skills.

1. Responsibility and Verification

Use AI Within the Scope You Can Verify

Code or solutions generated by AI should only be used if they are fully understood by the engineer. Simply copying and pasting code you don’t understand leaves you unprepared when problems arise. Avoid instructions that produce results you cannot personally verify for correctness.

Always Verify and Refine AI Outputs

AI-generated code is prone to errors and inconsistencies. It is not your final product by default. It requires understanding, refinement, and supplementation. Remember, the ultimate responsibility always lies with the developer.

2. Balancing Personal Growth

AI is an Assistant, Not the Answer

AI is like “training wheels” for thought, not the final solution provider. Over-reliance on AI is risky; you must cultivate the habit of thinking and verifying independently. Treat AI as an assistant for efficiency, not as a substitute for your own reasoning and decision-making.

Preserve Opportunities for Growth

Do not offload tasks entirely to AI without first trying to solve them yourself. View each challenge as a growth opportunity. By thinking on your own first and then leveraging AI, you can enhance your problem-solving abilities while making effective use of AI’s strengths.

For example, instead of asking AI to fix bugs or refactor code immediately, try to analyze the root cause yourself, then consult AI for additional insights. This approach deepens your understanding.

3. Communication

Align AI Usage with Team Policies

When unsure whether AI should be used, consult with your manager or mentor and confirm the team’s guidelines. This is particularly important for junior engineers who are still learning.

Prioritize Human Dialogue

Direct feedback from managers and mentors should take precedence over AI responses. Sharing implicit organizational knowledge and values through human communication is key to becoming a better engineer. Actively seeking feedback from colleagues not only improves technical skills but also enhances team collaboration and communication skills.

For instance, when uncertain about implementation approaches, consult your mentor first to learn your organization’s best practices and design philosophy.

4. Essential Skills

Understand AI’s Strengths and Weaknesses

Engineers should learn how to appropriately delegate tasks based on AI’s strengths and limitations. For many minor adjustments or simple fixes, doing the work manually is often more efficient than relying on AI.

Strengthen Problem-Solving Skills

Develop both the ability to understand and modify AI-generated code and the ability to solve problems independently. Rather than depending on AI entirely, use your own judgment and skills to collaborate with it effectively.

For example, being able to interpret the intent and side effects of AI-generated code will help prevent issues during production.

Why Over-Reliance on AI is Risky

Excessive dependence on AI can lead to:

Stagnation in Skill Development: Relying on AI too often can hinder the growth of your own problem-solving and coding abilities.
Lack of Understanding: Using AI-generated code without understanding it makes future debugging and modifications difficult.
Reduced Efficiency: Relying on AI for simple fixes may actually consume more time than solving the problem yourself.
Limited Creativity: Over-reliance on AI suggestions can restrict your ability to develop unique or innovative solutions.

Striking the Right Balance

To leverage AI effectively, consider the following balance:

Always think through problems yourself first.
Choose specific scenarios for AI use (e.g., routine tasks or automating documentation).
Evaluate AI output critically (e.g., reviewing logic or security concerns).
Actively seek feedback from humans.
Switch between AI and manual problem-solving appropriately.

Conclusion

AI can either accelerate or hinder growth, depending on how it is used. For engineers at the start of their careers, it is crucial not to over-rely on AI but to balance AI utilization skills with independent problem-solving abilities, treating AI as a growth partner. Maintaining the right distance from AI will significantly influence future development as an engineer.

For senior engineers, AI can provide higher-level perspectives, new ideas, and increased efficiency. Mastering AI usage can lead to better abstraction of complex issues, faster problem-solving, and improved team productivity.

Junior engineers should first develop independent thinking and proper AI usage skills, progressively using AI in more advanced ways as they grow. Viewing AI not merely as a tool but as a partner for personal development will pave the way to becoming a stronger engineer.

📝 Introducing shokika.css - Lightweight Reset for Modern Web Development

hiro — Sat, 05 Jul 2025 09:25:16 +0000

If you're a web developer, "CSS Reset" is part of your standard toolkit. For years, libraries like normalize.css have saved us from the frustrating inconsistencies between browsers.

But times have changed. Internet Explorer support is officially a thing of the past, and most new projects exclusively target modern browsers.

This new reality begs the question: "Is a reset CSS that continues to support legacy browsers still the best choice?"

The answer might be shokika.css, a library that takes a clear stance: by specializing in modern environments, it achieves exceptional ease of use.

Why Choose shokika.css Over normalize.css?

The greatest advantage of shokika.css is its bold decision to cut ties with legacy browser support.

1. Simplicity and Lightweightness Through a Modern Focus

Libraries like normalize.css include numerous hacks and fallbacks to accommodate the quirks of older browsers. While once necessary for compatibility, this is now just "dead weight" for projects targeting modern browsers.

shokika.css sheds this weight. As a result, its file size is extremely small, and its code is clean and intuitive. Developers get the pure benefits of a reset without worrying about legacy baggage.

2. Excellent Synergy with Modern CSS Architecture

While CSS Cascade Layers is a CSS feature that can be used with any stylesheet, its true power is unlocked when combined with a pure, foundational reset like shokika.css.

By placing shokika.css in the lowest cascade layer (reset), you eliminate any risk of your reset styles unintentionally overriding your component or utility styles later on.

/* Define your cascade layers */
@layer reset, base, components;

/* Place shokika.css in the bottom-most 'reset' layer */
@import 'shokika.css' layer(reset);

/* Now you can write component styles without worrying about specificity conflicts */
@layer components {
  .button {
    /* ... */
  }
}

The library's "do one thing well" simplicity meshes perfectly with this modern architectural approach.

How to Use (Project Integration)

shokika.css offers several ways to integrate it into your project, ensuring flexibility for any development environment.

1. CDN (The Easiest Way)

You can get started immediately by adding this single line to the <head> of your HTML file. It's perfect for prototyping or small projects.

<link rel="stylesheet" href="https://unpkg.com/shokika.css@latest/dist/shokika.min.css" />

2. Install via Package Manager

For projects in a Node.js environment, install it using your preferred package manager.

npm

npm install shokika.css

Yarn

yarn add shokika.css

pnpm

pnpm add shokika.css

3. Import into CSS/SCSS Files

After installation, import shokika.css into your project's main CSS or SCSS file.

Basic Import

@import 'shokika.css';

Recommended Import with CSS Cascade Layers

As mentioned, using Cascade Layers allows for a more robust CSS architecture.

@layer reset, base, components;

@import 'shokika.css' layer(reset);

4. Use with CSS-in-JS (React, Vue, etc.)

If you are using a CSS-in-JS library like Emotion or Styled Components, you can import the styles directly as a string.

Emotion Example

import { css, Global } from '@emotion/react';
import resetCSS from 'shokika.css/dist/string';

const globalStyle = css`
  ${resetCSS}
  /* You can add your own global styles here */
`;

export const CSSReset = () => <Global styles={globalStyle} />;

Styled Components Example

import { createGlobalStyle } from 'styled-components';
import resetCSS from 'shokika.css/dist/string';

const GlobalStyle = createGlobalStyle`
  ${resetCSS}
`;

Conclusion: Choose the Right Reset for Your "Modern" Project

The role normalize.css has played in web development is immense. However, if your next project targets only modern browsers, shokika.css is a more lightweight, easier-to-handle, and more future-forward choice.

It's time to shed the legacy weight and start developing on a clean, modern foundation. shokika.css is the perfect tool for the job.

If you find shokika.css helpful, please consider giving the project a ⭐️ on GitHub!

Your support helps the project reach more developers and encourages further development.

shokika.css GitHub Repository

[GitHub Actions] How to Automatically Run npm Update and Create a Pull Request

hiro — Tue, 05 Dec 2023 03:46:16 +0000

Background

There was a need to regularly run npm update to keep dependency packages up to date, but doing it manually was cumbersome, so I wanted to automate it using GitHub Actions.

Specifications

Execute the workflow every Monday.
Run npm update.
Check if package-lock.json has been updated.
Commit package-lock.json and create a Pull Request.

Implementation

1. Execute the Workflow Every Monday

on:
  schedule:
    - cron: '0 0 * * 1'

2. Run `npm update`

- name: Update packages
  run: npm update

3. Check for Changes in `package-lock.json`

- name: Check for changes
  id: git-check
  run: |
    git diff --exit-code || echo "changes=true" >> $GITHUB_OUTPUT

Check for differences using git diff --exit-code. If there are changes, the exit code becomes 1, and changes=true is added to $GITHUB_OUTPUT.

4. Create a Pull Request

First, execute only if there are changes using if: ${{ steps.git-check.outputs.changes == 'true' }}.

For creating Pull Requests, use the action peter-evans/create-pull-request. This action allows batch specification of commits (add-paths), so it handles everything from committing package-lock.json to creating the Pull Request.

The Create Pull Request action will:

Check for repository changes in the Actions workspace. This includes:

untracked (new) files

tracked (modified) files

commits made during the workflow that have not been pushed

Commit all changes to a new branch, or update an existing pull request branch.

Create a pull request to merge the new branch into the base—the branch checked out in the workflow.

The definition is as follows:

- name: Create Pull Request
  if: ${{ steps.git-check.outputs.changes == 'true' }}
  uses: peter-evans/create-pull-request@v5
  with:
    token: ${{ secrets.BOT_TOKEN }}
    base: develop
    add-paths: package-lock.json
    commit-message: Update npm dependencies
    title: '[Automated] Update npm dependencies'
    body: 'Automated changes by GitHub Actions'
    branch: automated-npm-update
    delete-branch: true

Specifying token as ${{ secrets.GITHUB_TOKEN }} is also fine, but if you want to trigger another Actions workflow, you need to prepare a different token.

Additionally, even if executed consecutively, commits will be made to the same branch, and the Pull Request will be updated (without failing to create a new Pull Request).

Final Workflow

The workflow created is broadly as follows:

name: Automated npm update

on:
  schedule:
    - cron: '0 0 * * 1'
  workflow_dispatch:

permissions:
  contents: write
  pull-requests: write

jobs:
  npm-update:
    env:
      pr_title: '[Automated] Update NPM dependencies'

    runs-on: ubuntu-latest

    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version-file: '.node-version'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Update packages
        run: npm update

      - name: Check for changes
        id: git-check
        run: |
          git diff --exit-code || echo "changes=true" >> $GITHUB_OUTPUT

      - name: Create Pull Request
        if: ${{ steps.git-check.outputs.changes == 'true' }}
        uses: peter-evans/create-pull-request@v5
        with:
          token: ${{ secrets

.BOT_TOKEN }}
          base: develop
          add-paths: package-lock.json
          commit-message: Update npm dependencies
          title: ${{ env.pr_title }}
          body: 'Automated changes by GitHub Actions'
          branch: automated-npm-update
          delete-branch: true

[Java] How to Insert Line Breaks in a String

hiro — Mon, 04 Dec 2023 06:47:53 +0000

Differences in Line Break Codes

The line break code can vary depending on the operating system.

Windows	UNIX
`\r\n`	`\n`

Examples

Line breaks can be achieved by directly including the line break code in the string.

String text = "Hello \r\nWorld";
System.out.println(text);

Hello
World

Example Absorbing Environmental Dependencies

Java offers a standard feature to obtain environment-independent line break codes.

By using System.getProperty("line.separator") as shown below, you can get the appropriate line break code for the execution environment.

public static final String LINE_SEPARATOR = System.getProperty("line.separator");

String test = "Hello" + LINE_SEPARATOR + "World";
System.out.println(test);

It's recommended to use System.getProperty("line.separator") for line breaks in Java.

[Accessibility] Points to Consider When Adding aria-label to Icon Font Elements

hiro — Mon, 04 Dec 2023 06:38:24 +0000

Premise of Icon Fonts

The following is an example of defining Font Awesome:

.fab {
  font-family: "Font Awesome 5 Brands";
}

.fa-twitter::before {
  content: "\f099";
}

<span class="fab fa-twitter"></span>

Icon fonts render icons by placing character glyphs corresponding to the icons in pseudo-elements.

Purpose of Accessibility

Similar to the alt attribute of <img>, alternative text can be described using aria-label, allowing screen readers to convey appropriate meaning.

Implementation

Decorative Icons

For decorative icons that do not need to be read by screen readers, add aria-hidden="true".

<span class="fab fa-twitter" aria-hidden="true"></span>

Meaningful Icons

For icons that need a description for screen readers, add aria-label.

<span class="fab fa-twitter" aria-label="Twitter"></span>

Icons Accompanied by Text

If there is meaningful text alongside the icon, having aria-label can cause screen readers to read it twice. In such cases, add aria-hidden="true" as shown below.

<a href="https://twitter.com/">
  <span class="fab fa-twitter" aria-hidden="true"></span>
  Twitter
</a>

[Accessibility] Points to Consider When Adding Alternative Text (alt) to Images

Mechanically Detecting Accessibility Violations

hiro — Fri, 01 Dec 2023 03:53:09 +0000

This article is in process of translation.
The original text is at https://b.0218.jp/202312010000.html 🙏

Introduction

Web accessibility (hereinafter referred to as accessibility) is a crucial element to ensure that all users can use websites and information systems. However, despite recognizing the importance of accessibility, many developers do not know how to detect and improve accessibility violations.

This article focuses on methods to mechanically detect accessibility violations and explains their implementation.

Verification Tools

The use of verification tools is very effective in finding and improving accessibility violations. There are various types of verification tools, for example, using Lighthouse integrated into Chrome DevTools allows for easy verification of accessibility.

Results verified with Lighthouse in Chrome DevTools

Furthermore, Lighthouse¹ uses axe-core as the audit engine for accessibility, and by using it directly, more detailed information can be obtained. Thus, verification tools clarify specific problems, allowing for the formulation of improvement measures based on them.

What is axe-core?

axe-core is an accessibility testing library for websites, developed by Deque Systems, a leading vendor in accessibility. axe-core provides various rules compliant with WCAG 2.0, 2.1, and 2.2² levels A, AA, and AAA, including common best practices in accessibility, such as ensuring each page has an h1 heading. The rules are grouped by WCAG level and best practices³⁴.

Furthermore, browser extensions and VS Code extensions (e.g., axe Accessibility Linter) are also available.

How to Use

axe-core offers a package @axe-core/puppeteer that is convenient for integration with Puppeteer.

The core of axe-core requires embedding the library into the target site for execution, and there's no feature to insert and execute axe externally. Therefore, to verify externally, tools like headless browsers are necessary, and for headless browser verification, @axe-core/puppeteer is convenient.

axe-core-npm also offers other packages such as:

Choose the appropriate package according to your needs.

Moreover, for reporting the verification results of axe-core, a package called axe-reports is provided by volunteers. It allows the export of axe-core's verification results in CSV or TSV formats, enabling the generation of ideal verification results by combining these.

インストール

まずは、各種パッケージをインストールする。

npm install puppeteer @axe-core/puppeteer axe-reports

コード例

公式で記載されている実装例にaxe-reportsを組み合わせた形で実装すると以下のようになる。

import { AxePuppeteer } from '@axe-core/puppeteer';
import puppeteer from 'puppeteer';
import AxeReports from 'axe-reports';

(async () => {
  const browser = await puppeteer.launch({ headless: 'new' });
  const page = await browser.newPage();

  await page.setBypassCSP(true);
  await page.goto('https://dequeuniversity.com/demo/mars/');

  try {
    AxeReports.createCsvReportHeaderRow();
    const results = await new AxePuppeteer(page).analyze();
    AxeReports.createCsvReportRow(results);
  } catch (e) {
    // do something with the error
  }

  await browser.close();
})();

対象のURLにヘッドレスブラウザでアクセスをして、Pageをaxe（AxePuppeteer）に渡して検証する。検証結果は、axe-reportsによって、CSVの形式で出力する。

大まかな実装は上記の通りだが、これを使い勝手の良いように整えていく。

検証するルール（規格）を指定する

withTags()メソッドを使うことで、検証するルール（規格）の指定もできる。

await new AxePuppeteer(page).withTags(['wcag2a', 'wcag2aa', 'wcag2aaa', 'wcag21a', 'wcag21aa', 'wcag21aaa']).analyze();

指定できるタグは以下の通り。用途に応じて適切な規格を指定できる。

Tag Name Accessibility Standard / Purpose

wcag2a WCAG 2.0 Level A

wcag2aa WCAG 2.0 Level AA

wcag2aaa WCAG 2.0 Level AAA

wcag21a WCAG 2.1 Level A

wcag21aa WCAG 2.1 Level AA

wcag22aa WCAG 2.2 Level AA

best-practice Common accessibility best practices

Section 2: API Reference - Axe-core Tagsより抜粋

Tag Name	Accessibility Standard / Purpose
`wcag2a`	WCAG 2.0 Level A
`wcag2aa`	WCAG 2.0 Level AA
`wcag2aaa`	WCAG 2.0 Level AAA
`wcag21a`	WCAG 2.1 Level A
`wcag21aa`	WCAG 2.1 Level AA
`wcag22aa`	WCAG 2.2 Level AA
`best-practice`	Common accessibility best practices

たとえば、対象のサイトがWCAG 2.2 Level AAに準拠していることを確認したい場合は wcag22aa を指定するといった具合である。

実装

使い勝手の良いように実装していく。以下の仕様で実装をする。

複数の指定されたURLの全てのページを検証する
出力結果を日本語化する

以降、それぞれの実装のコードを説明用に抜粋したものを紹介していく（完全なコードは別途公開する）。

複数の指定されたURLの全てのページを検証する

urls.txt というURLの設定ファイルを用意する（1行毎にURLを記載する）

   #例
   https://example.com/
   https://example.jp/
   https://example.jp/aaa

設定ファイルからURLを読み込み、それぞれのURLに対して検証をしていく

   import fs from 'node:fs';

   const readUrls = async () => {
     const urlsFile = await fs.promises.readFile('./urls.txt', 'utf-8');

     const urls = urlsFile
       .replace(/\r\n?/g, '\n')
       .split('\n')
       .filter((url) => url);

     return urls;
   };

readUrls()を組み込むと以下のような形になる。urlに対して非同期処理の並列実行をPromise.all()で行う。

import { AxePuppeteer } from '@axe-core/puppeteer';
import puppeteer from 'puppeteer';
import AxeReports from 'axe-reports';

const setupAndRunAxeTest = async (url, browser) => {
  const page = await browser.newPage();
  await page.setBypassCSP(true);
  await page.goto(url);

  try {
    const results = await new AxePuppeteer(page).analyze();
    AxeReports.createCsvReportRow(results);
  } catch (e) {}
};

(async () => {
  AxeReports.createCsvReportHeaderRow();

  const urls = await readUrls();
  const browser = await puppeteer.launch({ headless: 'new' });

  try {
    await Promise.all(urls.map((url) => setupAndRunAxeTest(url, browser)));
  } catch (error) {
    console.error(`Error during tests: ${error}`);
  } finally {
    await browser.close();
  }
})();

出力結果を日本語化する

英語のままの出力で問題なければ以下の実装は不要。

見出しの日本語化

AxeReportsが出力するCSVヘッダは英語の固定値になっており変更できない（TSVも同様）。

// このような形で出力される
'URL,Volation Type,Impact,Help,HTML Element,Messages,DOM Element\r';

ここのロケールを変えたり、任意の文字を指定できないため、日本語で出力したい場合はAxeReports.createCsvReportHeaderRow()を使わず自前で出力する必要がある。

単純に時前でCSVファイルを作成するだけである。

import fs from 'node:fs';

const CSV_FILE_PATH = `./result.csv`;

// 元のヘッダー部分を日本語化したもの
const CSV_HEADER = 'URL,種別,影響度,ヘルプ,HTML要素,メッセージ,DOM要素\r';

// 既存のCSVファイルがあれば削除
if (fs.existsSync(CSV_FILE_PATH)) {
  fs.rmSync(CSV_FILE_PATH);
}

// 新しいCSVファイルを作成
fs.writeFileSync(CSV_FILE_PATH, CSV_HEADER);

// 中略

AxeReports.createCsvReportRow(results);

検証結果の日本語化

axeの検証結果は標準では英語で出力されるが、日本語のロケール（axe-core/locales/ja.json）が用意されているため、それを利用して日本語化できる。
ロケールの指定は、以下のようにAxePuppeteerのconfigure()メソッドの引数に指定することで日本語化できる。

import AXE_LOCALE_JA from 'axe-core/locales/ja.json';

// 中略

const results = await new AxePuppeteer(page).configure({ locale: AXE_LOCALE_JA }).analyze();

検証結果の影響度

メッセージ部分はロケールを指定することで日本語化されるが、影響度は英語のままで出力される。

影響度として、critical・serious・moderate・minorが定義されている。出力した際に分かりやすいように以下のように置き換える。

英語	日本語
critical	緊急（Critical）
serious	深刻（Serious）
moderate	普通（Moderate）
minor	軽微（Minor）

AxePuppeteerのanalyze()メソッドの戻り値に対して、指定の影響度の文字列を置き換える。AxeResultsの値に応じて置換をしていく。

import type { AxeResults, ImpactValue } from 'axe-core';

type AxeResultsKeys = keyof Omit<
  AxeResults,
  'toolOptions' | 'testEngine' | 'testRunner' | 'testEnvironment' | 'url' | 'timestamp'
>;

const CSV_TRANSLATE_RESULT_GROUPS: AxeResultsKeys[] = ['inapplicable', 'violations', 'incomplete', 'passes'];
const CSV_TRANSLATE_IMPACT_VALUE = {
  critical: '緊急 (Critical)',
  serious: '深刻 (Serious)',
  moderate: '普通 (Moderate)',
  minor: '軽微 (Minor)',
};

const replaceImpactValues = (axeResult: AxeResults): AxeResults => {
  const result = { ...axeResult };

  for (const key of CSV_TRANSLATE_RESULT_GROUPS) {
    if (result[key] && Array.isArray(result[key])) {
      const updatedItems = [];
      for (const item of result[key]) {
        if (item.impact && CSV_TRANSLATE_IMPACT_VALUE[item.impact]) {
          updatedItems.push({
            ...item,
            impact: CSV_TRANSLATE_IMPACT_VALUE[item.impact] as ImpactValue,
          });
        } else {
          updatedItems.push(item);
        }
      }
      result[key] = updatedItems;
    }
  }

  return result;
};

// 中略

const results = await new AxePuppeteer(page)
  .configure({ locale: AXE_LOCALE_JA })
  .analyze()
  .then((analyzeResults) => replaceImpactValues(analyzeResults));

その他

axeとは直接関係ない部分を紹介する。

デバイスの指定

以下のようにpage.emulate()メソッドを使うことでデバイス指定ができる。

// モバイルの指定をした場合
const userAgent = await browser.userAgent();
await page.emulate({
  userAgent,
  viewport: {
    width: 375,
    height: 812,
    isMobile: true,
    hasTouch: true,
  },
});

page.emulate の userAgent は必須項目のため、現状の browser.userAgent() を利用する。

さらにデバイスのフラグを.envファイルにもたせるなどして、切り替えできるようにしておくと良い。

ページ最下部までスクロールする

スクロールすることで読み込まれるコンテンツを検証するために、ページの最下部までスクロールする。

無限スクロールが実装されているページなどでは永久にスクロールが終わらなくなってしまうため、スクロール回数の上限を設けている。

/**
 * 指定した時間だけ待機する関数
 * @param ms 待機時間（ミリ秒）
 */
const waitForTimeout = (ms: number): Promise<void> => {
  return new Promise((resolve) => setTimeout(resolve, ms));
};

/**
 * ページの最下部までスクロールする
 */
const scrollToBottom = async (page: Page, maxScrolls = 10, waitTime = 3000): Promise<void> => {
  let previousHeight = 0;
  let scrollCount = 0;

  while (scrollCount < maxScrolls) {
    // 現在のページの高さを取得
    const currentHeight: number = await page.evaluate(() => document.body.scrollHeight);

    // 前回と高さが変わらなければ終了
    if (previousHeight === currentHeight) break;

    // ページの最下部までスクロール
    await page.evaluate('window.scrollTo(0, document.body.scrollHeight)');
    previousHeight = currentHeight;

    // 指定された時間だけ待機
    await waitForTimeout(waitTime);

    // スクロール回数をカウント
    scrollCount++;
  }
};

完成したコード例

これまでの実装例を組み合わせると、以下のような形になった。実際はもう少しファイル分割をすると良い。

import 'dotenv/config';

import fs from 'node:fs';
import { AxePuppeteer } from '@axe-core/puppeteer';
import type { Spec, AxeResults, ImpactValue } from 'axe-core';
import AxeReports from 'axe-reports';
import puppeteer, { Browser, Page } from 'puppeteer';
import AXE_LOCALE_JA from 'axe-core/locales/ja.json';

import type { AxeResultsKeys } from './types';

export const FILE_NAME = 'result';
export const FILE_EXTENSION = 'csv';
export const CSV_FILE_PATH = `./${FILE_NAME}.${FILE_EXTENSION}`;
export const CSV_HEADER = 'URL,種別,影響度,ヘルプ,HTML要素,メッセージ,DOM要素\r';
export const CSV_TRANSLATE_RESULT_GROUPS: AxeResultsKeys[] = ['inapplicable', 'violations', 'incomplete', 'passes'];
export const CSV_TRANSLATE_IMPACT_VALUE = {
  critical: '緊急 (Critical)',
  serious: '深刻 (Serious)',
  moderate: '普通 (Moderate)',
  minor: '軽微 (Minor)',
};

/**
 * URLをファイルから非同期で読み込む
 */
const readUrls = async (): Promise<string[]> => {
  const urlsFile = await fs.promises.readFile('./urls.txt', 'utf-8');

  const urls = urlsFile
    .replace(/\r\n?/g, '\n')
    .split('\n')
    .filter((url) => url);

  return urls;
};

/**
 * 指定した時間だけ待機する関数
 * @param ms 待機時間（ミリ秒）
 */
const waitForTimeout = (ms: number): Promise<void> => {
  return new Promise((resolve) => setTimeout(resolve, ms));
};

/**
 * ページの最下部までスクロールする
 */
const scrollToBottom = async (page: Page, maxScrolls = 10, waitTime = 3000): Promise<void> => {
  let previousHeight = 0;
  let scrollCount = 0;

  while (scrollCount < maxScrolls) {
    const currentHeight: number = await page.evaluate(() => document.body.scrollHeight);

    if (previousHeight === currentHeight) break;

    await page.evaluate('window.scrollTo(0, document.body.scrollHeight)');
    previousHeight = currentHeight;

    await waitForTimeout(waitTime);

    scrollCount++;
  }
};

/**
 * Axeの結果の影響度の値を日本語に置き換える
 */
const replaceImpactValues = (axeResult: AxeResults): AxeResults => {
  const result = { ...axeResult };

  for (const key of CSV_TRANSLATE_RESULT_GROUPS) {
    if (result[key] && Array.isArray(result[key])) {
      const updatedItems = [];
      for (const item of result[key]) {
        if (item.impact && CSV_TRANSLATE_IMPACT_VALUE[item.impact]) {
          updatedItems.push({
            ...item,
            impact: CSV_TRANSLATE_IMPACT_VALUE[item.impact] as ImpactValue,
          });
        } else {
          updatedItems.push(item);
        }
      }
      result[key] = updatedItems;
    }
  }

  return result;
};

/**
 * Axeによるアクセシビリティテストを実行する
 */
const runAxeTest = async (page: Page, url: string): Promise<AxeResults> => {
  console.log(`Testing ${url}...`);

  // 指定されたURLにアクセス
  await page.goto(url, { waitUntil: ['load', 'networkidle2'] }).catch(() => {
    console.error(`Connection failed: ${url}`);
  });

  console.log(`page title: ${await page.title()}`);

  await scrollToBottom(page);

  const results = await new AxePuppeteer(page)
    .configure({ locale: AXE_LOCALE_JA } as unknown as Spec)
    .withTags(['wcag2a', 'wcag21a', 'best-practice'])
    .analyze()
    .then((analyzeResults) => replaceImpactValues(analyzeResults));

  return results;
};

/**
 * URLごとにページを設定し、アクセシビリティテストを実行する
 */
async function setupAndRunAxeTest(url: string, browser: Browser) {
  const page = await browser.newPage();
  await page.setBypassCSP(true);

  /**
   * process.env.DEVICE_TYPE
   * @type {"0" | "1" | undefined}
   * @description "0" はデスクトップ / "1" はモバイル
   */
  if (process.env.DEVICE_TYPE === '1') {
    const userAgent = await browser.userAgent();
    await page.emulate({
      userAgent,
      viewport: {
        width: 375,
        height: 812,
        isMobile: true,
        hasTouch: true,
      },
    });
  }

  try {
    const results = await runAxeTest(page, url);
    AxeReports.processResults(results, FILE_EXTENSION, FILE_NAME);
  } catch (error) {
    console.error(`Error testing ${url}:`, error);
  } finally {
    await page.close();
  }
}

(async () => {
  const urls = await readUrls();

  if (fs.existsSync(CSV_FILE_PATH)) {
    fs.rmSync(CSV_FILE_PATH);
  }
  fs.writeFileSync(CSV_FILE_PATH, CSV_HEADER);

  const browser = await puppeteer.launch({ headless: 'new' });

  try {
    await Promise.all(urls.map((url) => setupAndRunAxeTest(url, browser)));
  } catch (error) {
    console.error(`Error during tests: ${error}`);
  } finally {
    await browser.close();
  }
})();

検証結果

完成したコードでデジタル庁のURLを指定してアクセシビリティの検証をしてみる。

URL https://www.digital.go.jp/
ルール

  withTags(['wcag2a', 'wcag21a', 'best-practice']);

その他
- Node.js上で実行するが、TypeScriptで実装しているため、ts-nodeもしくはnode -r esbuild-registerなどを使って実行する

スクリプトの実行後、以下のような結果がCSV出力された。日本語化の対応によって、影響度やヘルプ（のURL）、メッセージが日本語で出力されていることが確認できる。

URL,種別,影響度,ヘルプ,HTML要素,メッセージ,DOM要素
https://www.digital.go.jp/,heading-order,普通 (Moderate),https://dequeuniversity.com/rules/axe/4.8/heading-order?application=axe-puppeteer&lang=ja,<h5 class="card-image__title text-r">マイナンバー制度・マイナンバーカード</h5>,見出しの順序が無効です,a[href$="mynumber"] > .card-image__text > h5
https://www.digital.go.jp/,page-has-heading-one,普通 (Moderate),https://dequeuniversity.com/rules/axe/4.8/page-has-heading-one?application=axe-puppeteer&lang=ja,<html lang="ja" dir="ltr" prefix="og: https://ogp.me/ns#" class=" js">,,html
https://www.digital.go.jp/,region,普通 (Moderate),https://dequeuniversity.com/rules/axe/4.8/region?application=axe-puppeteer&lang=ja,<div class="template__pagetop">,ページの一部のコンテンツがランドマークに含まれていません,.template__pagetop
https://www.digital.go.jp/,svg-img-alt,深刻 (Serious),https://dequeuniversity.com/rules/axe/4.8/svg-img-alt?application=axe-puppeteer&lang=ja,<svg role="img" class="icon icon--12px icon--arrow-rightwards">  <path xmlns="http://www.w3.org/2000/svg" d="M7.3813 1.67358L12.3591 6.59668L7.3813 11.5198L6.4582 10.5967L9.85825 7.19663H2.08008V5.99663H9.85816L6.4582 2.59668L7.3813 1.67358Z"></path></svg>,要素にタイトルを示す子要素が存在しません--aria-label属性が存在しない、または空です--aria-labelledby属性が存在しない、存在しない要素を参照している、または空の要素を参照しています--要素にtitle属性が指定されていません,a[href$="newgraduates/"] > .mdcontainer-button-inner__text > .svg-wrapper > .icon--arrow-rightwards.icon--12px.icon

出力された結果を見ると、以下のようなアクセシビリティ違反がある。

imgロールを持つ<svg>要素には代替テキストが存在しなければなりません
見出しのレベルは1つずつ増加させなければなりません
ページにはレベル1の見出しが含まれていなければなりません
ページのすべてのコンテンツはlandmarkに含まれていなければなりません

出力結果には、Deque Universityへのリンクが含まれているため、そこから詳細を確認できる（例：https://dequeuniversity.com/rules/axe/4.8/heading-order?application=axe-puppeteer&lang=ja）。

また、axe DevToolsでも同様の設定で実行して、同様の結果が得られている。

axe DevToolsの検査結果

Conclusion

Verification tools are highly effective in detecting accessibility violations and are essential for improving the accessibility of websites. These tools quickly identify technical issues and facilitate the development of improvement strategies.
However, since verification tools cannot detect all accessibility issues⁵, it is important not to rely solely on these tools. Human reviews and evaluations based on actual user experiences are also crucial.
Verification tools are aids in enhancing accessibility, but they should be complemented by continuous monitoring and improvement. Ultimately, the combined efforts of these approaches will lead to a better, more accessible web experience for all users.

The same results can be obtained using PageSpeed Insights. ↩
WCAG (Web Content Accessibility Guidelines) is an international standard guideline created by W3C to make web content more accessible. It includes specific criteria to enable users with various disabilities, such as visual, auditory, or motor impairments, to access web content easily. ↩
These are rules accepted in the industry to enhance user experience, not necessarily conforming to WCAG success criteria. ↩
List of axe-core rules ↩
This refers to the limitation of verification tools in detecting every possible accessibility issue. ↩

[CSS design] I think about specifying z-index difficult to break

hiro — Sun, 22 May 2022 14:47:04 +0000

Summary

Defines the z-index value to be specified for each component.

Motivation

I want to avoid z-index conflicts
Want to clarify the reason for specifying z-index
Don't want to increase z-index each time more components are added

Prerequisites

Rules for `z-index`

Do not use z-index as much as possible.
Use z-index from 0 to 4.
As a rule, do not use negative numbers such as -1.

Layer Stack rules

Define the z-index value that a component should have on a layer (hierarchy) for each role.
Increase the z-index value as the layer stacks up.

Layer Stack 4 : `z-index: 4`.

Element to be placed on top in any state.

Modal
Drawer
Overlay

Layer Stack 3 : `z-index: 3`

Elements that are always placed on top.

An element that is always placed on top.

Global header (e.g., fixed header to follow)

Layer Stack 2 : `z-index: 2`.

Tooltips
Pop-overs
Floating buttons (e.g., arrow buttons for carousels, etc.)

Layer Stack 1 : `z-index: 1`.

Placed on top of an element that does not have a stack.

Badge

Define `z-index`.

:root {
  --layer-stack-1: 1;
  --layer-stack-2: 2;
  --layer-stack-3: 3;
  --layer-stack-4: 4;
}

.modal {
  z-index: var(--layer-stack-4);
}

.modal-in-modal {
  z-index: calc(var(--layer-stack-4) + 1);
}

Rules for `isolation`

There may be a case where the z-index conflicts between components in the Layer Stack definition alone, resulting in unintended overlapping. In such a case, you can solve the problem by using isolation to generate stacking context in the root of the component.

.special-components {
  isolation: isolate; /* generate stacking context */
  position: absolute;
}

.special-components__item {
  position: absolute;
  z-index: 100;
}

.modal {
  position: absolute;
  z-index: var(--layer-stack-4);
}

Basically, it is preferable to use an HTML structure with no problems with just a z-index specification, but there is a high possibility of unintended overlap with other components when a specification such as z-index: calc(var(--layer-stack-2) + 1); is used. It is preferable to specify isolation for the root of a component whose child elements have a z-index specification.

Incidentally, before the advent of isolation, there was a hack to generate stacking contexts by specifying transform without side-effects (e.g. transform: scale(1)).

Summary

Specify z-index according to Layer Stack rules.
Specify isolation: isolate for component root

Awesome dev.to

hiro — Wed, 15 Nov 2017 07:07:40 +0000

I was impressed by the loading speed of this site!

I'd like to refer to the processing of this site.

DEV Community: hiro

AI Utilization Guidelines for Continuous Engineer Growth

AI Utilization Guidelines for Continuous Engineer Growth

Introduction

Four Principles for Leveraging AI Without Hindering Growth

1. Responsibility and Verification

Use AI Within the Scope You Can Verify

Always Verify and Refine AI Outputs

2. Balancing Personal Growth

AI is an Assistant, Not the Answer

Preserve Opportunities for Growth

3. Communication

Align AI Usage with Team Policies

Prioritize Human Dialogue

4. Essential Skills

Understand AI’s Strengths and Weaknesses

Strengthen Problem-Solving Skills

Why Over-Reliance on AI is Risky

Striking the Right Balance

Conclusion

📝 Introducing shokika.css - Lightweight Reset for Modern Web Development

Why Choose shokika.css Over normalize.css?

1. Simplicity and Lightweightness Through a Modern Focus

2. Excellent Synergy with Modern CSS Architecture

How to Use (Project Integration)

1. CDN (The Easiest Way)

2. Install via Package Manager

3. Import into CSS/SCSS Files

4. Use with CSS-in-JS (React, Vue, etc.)

Conclusion: Choose the Right Reset for Your "Modern" Project

[GitHub Actions] How to Automatically Run npm Update and Create a Pull Request

Background

Specifications

Implementation

1. Execute the Workflow Every Monday

2. Run npm update

3. Check for Changes in package-lock.json

4. Create a Pull Request

Final Workflow

[Java] How to Insert Line Breaks in a String

Differences in Line Break Codes

Examples

Example Absorbing Environmental Dependencies

[Accessibility] Points to Consider When Adding aria-label to Icon Font Elements

Premise of Icon Fonts

Purpose of Accessibility

Implementation

Decorative Icons

Meaningful Icons

Icons Accompanied by Text

Related

Mechanically Detecting Accessibility Violations

Introduction

Verification Tools

What is axe-core?

How to Use

インストール

コード例

検証するルール（規格）を指定する

実装

複数の指定されたURLの全てのページを検証する

出力結果を日本語化する

見出しの日本語化

検証結果の日本語化

検証結果の影響度

その他

デバイスの指定

ページ最下部までスクロールする

完成したコード例

検証結果

Conclusion

[CSS design] I think about specifying z-index difficult to break

Summary

Motivation

Prerequisites

Rules for z-index

Layer Stack rules

Layer Stack 4 : z-index: 4.

Layer Stack 3 : z-index: 3

Layer Stack 2 : z-index: 2.

2. Run `npm update`

3. Check for Changes in `package-lock.json`

Rules for `z-index`

Layer Stack 4 : `z-index: 4`.

Layer Stack 3 : `z-index: 3`

Layer Stack 2 : `z-index: 2`.

Layer Stack 1 : `z-index: 1`.

Define `z-index`.

Rules for `isolation`