optics-context

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Discovering Optics Classes

查找Optics类

When you need classes follow these steps:

Check
```
skills/optics-context/assets/components.json
```
for the appropriate component, modifiers, and attributes.

Often you may need to modify these components to better fit the context or need. Use BEM CSS structure to create modifiers and variants as needed. Use existing tokens when available to ensure consistency.

If you don't find an appropriate component, search in
```
app/assets/stylesheets
```
for any relevant components.
If nothing is found, create a new component in a CSS file named after the page that we're on.

If you're creating new classes, always use existing CSS tokens. You can find these in the
```
skills/optics-context/assets/tokens.json
```
file.

当你需要使用相关类时，请遵循以下步骤：

查看
```
skills/optics-context/assets/components.json
```
文件，找到合适的组件、修饰符和属性。

通常你可能需要修改这些组件以更好地适配上下文或需求。根据需要使用BEM CSS结构创建修饰符和变体。尽可能使用现有令牌以确保一致性。

如果找不到合适的组件，在
```
app/assets/stylesheets
```
中搜索相关组件。
如果仍未找到，在以当前页面命名的CSS文件中创建新组件。

创建新类时，务必使用现有的CSS令牌。你可以在
```
skills/optics-context/assets/tokens.json
```
文件中找到这些令牌。

Modifying Optics Classes

修改Optics类

When modifying Optics classes, follow these guidelines:

Always ensure that changes align with the overall design system principles.
Follow BEM naming conventions for any new classes.

Add changes to the appropriate CSS file in

app/assets/stylesheets/components/overrides/{component.css}

Ensure that you import any new css files in the
```
application.scss
```
Elements and modifiers should be nested under the block
Magic numbers should be avoided
Classes should have intentional-revealing names.

修改Optics类时，请遵循以下指南：

始终确保修改符合整体设计系统原则。
为所有新类遵循BEM命名规范。

将修改添加到

app/assets/stylesheets/components/overrides/{component.css}

中对应的CSS文件。

确保在
```
application.scss
```
中导入所有新的CSS文件。
元素和修饰符应嵌套在块级元素下。
避免使用魔法数字。
类名应具有明确的语义。

Fixing Optics Violations

修复Optics规范违规问题

As CSS is created or modified, it's important to be looking for Optics violations. These would include:

Hard-coded colors
- ```
#fff
```
  ,
```
#FFFFFF
```
  ,
```
rgb(...)
```
  ,
```
hsl(...)
```
  ,
```
rgba(...)
```
  , named colors like
```
white
```
- Gradients:
```
linear-gradient(...)
```
  containing literals
Hard-coded spacing/sizing
- ```
px
```
  ,
```
rem
```
  ,
```
em
```
  ,
```
%
```
  (sometimes),
```
vh/vw
```
  (maybe allowed depending on policy)
- ```
border-radius
```
  ,
```
gap
```
  ,
```
padding
```
  ,
```
margin
```
  ,
```
width/height
```
  when used as spacing primitives

Hard-coded shadows/borders

```
box-shadow: 0 1px 3px rgba(...)
```
```
border: 1px solid #ddd
```

"Almost token" mistakes
- ```
var(--op_color_primary...)
```
  (bad separators)
- ```
var(--op-color-primary-plus-one-on)
```
  (segment order wrong)
- Missed
```
--op-
```
  prefix

When violations are found, refactor the CSS to use the appropriate Optics tokens from

skills/optics-context/assets/tokens.json

If no appropriate token exists, create a new token following the guidelines below.

在创建或修改CSS时，务必留意Optics规范的违规情况。违规情况包括：

硬编码颜色
- ```
#fff
```
  、
```
#FFFFFF
```
  、
```
rgb(...)
```
  、
```
hsl(...)
```
  、
```
rgba(...)
```
  、
```
white
```
  这类命名颜色
- 渐变：包含字面量的
```
linear-gradient(...)
```
硬编码间距/尺寸
- ```
px
```
  、
```
rem
```
  、
```
em
```
  、
```
%
```
  （有时）、
```
vh/vw
```
  （是否允许取决于规则）
- 用作间距基础的
```
border-radius
```
  、
```
gap
```
  、
```
padding
```
  、
```
margin
```
  、
```
width/height
```

硬编码阴影/边框

```
box-shadow: 0 1px 3px rgba(...)
```
```
border: 1px solid #ddd
```

"类令牌"错误
- ```
var(--op_color_primary...)
```
  （分隔符错误）
- ```
var(--op-color-primary-plus-one-on)
```
  （段顺序错误）
- 遗漏
```
--op-
```
  前缀

找到违规问题后，重构CSS以使用

skills/optics-context/assets/tokens.json

中对应的Optics令牌。

如果没有合适的令牌，请按照以下指南创建新令牌。

Creating New Optics Tokens

创建新的Optics令牌

When creating new Optics tokens, follow these guidelines:

Always ensure that new tokens align with the overall design system principles.
Follow the established naming conventions for tokens.
New tokens created within a project should use a namespace prefix related to the project to avoid conflicts. For example, a project called "Your App" might use the prefix
```
--ya-
```
for its tokens.
Otherwise, use the standard token format as seen in the
```
skills/optics-context/assets/tokens.json
```
file.
Occasionally, it may be helpful to create new global tokens to fit into the main Optics token set for your project. In such cases, ensure that the new token is broadly applicable and follows the established naming conventions. Usually, these tokens would be very general, such as new spacing sizes, color shades, or typography styles that could be reused across multiple parts of the application.

创建新的Optics令牌时，请遵循以下指南：

始终确保新令牌符合整体设计系统原则。
遵循已有的令牌命名规范。
项目内创建的新令牌应使用与项目相关的命名空间前缀，避免冲突。例如，名为"Your App"的项目可以为其令牌使用
```
--ya-
```
前缀。
否则，使用
```
skills/optics-context/assets/tokens.json
```
文件中的标准令牌格式。
有时，创建新的全局令牌以融入项目的主Optics令牌集可能会有所帮助。在这种情况下，确保新令牌具有广泛的适用性并遵循已有的命名规范。通常，这些令牌非常通用，例如可在应用程序多个部分复用的新间距尺寸、颜色色调或排版样式。

Example CSS class

CSS类示例

css

.card {
  position: relative;
  border-radius: var(--_op-card-radius);
  background-color: var(--op-color-background);

  /* Modifiers */

  &.card--padded {
    padding: var(--op-space-medium);
  }


  /* Elements */
  .card__header,
  .card__body,
  .card__footer {
    padding: var(--op-space-medium);
  }

  .card__header {
    border-start-end-radius: var(--op-radius-medium);
    border-start-start-radius: var(--op-radius-medium);
  }

  .card__footer {
    border-end-end-radius: var(--op-radius-medium);
    border-end-start-radius: var(--op-radius-medium);
  }
}

css

.card {
  position: relative;
  border-radius: var(--_op-card-radius);
  background-color: var(--op-color-background);

  /* Modifiers */

  &.card--padded {
    padding: var(--op-space-medium);
  }


  /* Elements */
  .card__header,
  .card__body,
  .card__footer {
    padding: var(--op-space-medium);
  }

  .card__header {
    border-start-end-radius: var(--op-radius-medium);
    border-start-start-radius: var(--op-radius-medium);
  }

  .card__footer {
    border-end-end-radius: var(--op-radius-medium);
    border-end-start-radius: var(--op-radius-medium);
  }
}

Creating Optics Components

创建Optics组件

To create a new CSS component, follow these steps:

Create a CSS file for the new component and import it
Start by defining a css
```
.{component-name}
```
selector for the component. This will serve as the base style for the component and all its variants.
Create modifiers for any all variants of the component you defined in the previous step. This ensures that the base style is shared consistently across all variations.
When creating variants of the component, use the following syntax:
```
.{component-name}--{variant}
```
. It can be helpful to nest these under the main class with a
```
&.{component-name}--{variant}
```
to ensure they only work with that component.
For stylistic tweaks that apply to all variants, use modifiers following the BEM (Block, Element, Modifier) syntax. The modifier class should be in the format:
```
.{component-name}--{modifier}
```
just like the other variants.

As a general policy, each CSS component should live in its own file unless very closely related.

To illustrate these concepts, let's consider an example of a button. You can use the following template as a guide:

css

/* Define the main component */
.btn {
  /* Base styles for the button */

  /* Hover state */
  &:hover {
    /*
      Styles for the hovered button modifier
      ...
    */
  }

  /* Modifier: Large button */
  &.btn--large {
    /* Styles for the large button modifier */
  }

  /* Modifier: Disabled button */
  &.btn--disabled,
  &:disabled {
    /* Styles for the disabled button modifier */
  }
}

/* Variant: Primary button */
.btn.btn--primary {
  /*
    Specific styles for the primary button variant
    ...
  */
}

要创建新的CSS组件，请遵循以下步骤：

为新组件创建CSS文件并导入
首先为组件定义一个css
```
.{component-name}
```
选择器。这将作为组件及其所有变体的基础样式。
为上一步中定义的组件的所有变体创建修饰符。这确保基础样式在所有变体中保持一致。
创建组件变体时，使用以下语法：
```
.{component-name}--{variant}
```
。将这些变体嵌套在主类下，使用
```
&.{component-name}--{variant}
```
，确保它们仅适用于该组件，这会很有帮助。
对于适用于所有变体的样式调整，使用遵循BEM（块、元素、修饰符）语法的修饰符。修饰符类的格式应为：
```
.{component-name}--{modifier}
```
，与其他变体相同。

一般规则是，每个CSS组件应单独存放在一个文件中，除非它们关系非常紧密。

为了说明这些概念，让我们以按钮为例。你可以使用以下模板作为参考：

css

/* Define the main component */
.btn {
  /* Base styles for the button */

  /* Hover state */
  &:hover {
    /*
      Styles for the hovered button modifier
      ...
    */
  }

  /* Modifier: Large button */
  &.btn--large {
    /* Styles for the large button modifier */
  }

  /* Modifier: Disabled button */
  &.btn--disabled,
  &:disabled {
    /* Styles for the disabled button modifier */
  }
}

/* Variant: Primary button */
.btn.btn--primary {
  /*
    Specific styles for the primary button variant
    ...
  */
}